@puredesktop/platform-editor 1.0.0-beta.1 → 1.0.0-beta.2

package/src/extensions/autoReviewPrompts.ts

@@ -1,1442 +1,1442 @@
-import { Extension, type Editor } from '@tiptap/core'
-import {
-  applyCommentMarkToRange,
-  type CommentReviewStatus,
-  type CommentSeverity,
-  type CommentType,
-} from '../commentUtils.js'
-
-export const AUTO_CLAIM_REVIEW_PROMPT = `You are reviewing manuscript paragraphs for one thing only: CLAIMS — statements the author advances as true that a reader could reasonably doubt and ask "says who?" of.
-
-Not your job: fact-checking, grammar, style, citations. Those are handled elsewhere. You only decide whether a sentence makes a contestable assertion that may need support, and if so, leave one short note.
-
-GENRE: {{GENRE}}   (scholarly | trade | essay | fiction)
-
-────────────────────────────────────────────────────────
-STEP 1 — GATES. Run these first. A sentence must pass ALL of them to be eligible. Most sentences will not. Being silent is the correct, common outcome.
-
-GATE A — Is it a citation or reference?
-A reference-list entry, bibliography line, or inline citation (author-year, DOI, URL, bracketed number) is a pointer to a source, not a claim about the world. Never flag it; it is out of scope here. If the span is or sits inside a citation, stay silent.
-
-GATE B — Is it a contestable assertion about the world?
-This is the decisive gate. Most prose is not a claim. Stay silent if the sentence is:
-- narration or recounting of events ("Ryan created the documentation", "the group met and discussed")
-- description of a process or procedure (steps, what happens, who does what)
-- a statement of intent or sequence ("after X was agreed, Y would happen")
-- the author defining their own terms, notation, or labels — INCLUDING when the naming move uses a hedge verb. "We represent this as PR", "for our purposes Z means…", "traditional publishing could be described as RP", "this can be called the review stage", "we might label this X" are ALL definitions, not claims. A hedge word ("could", "might", "can be") in front of a naming move does not turn a definition into a contestable assertion. The author owes no evidence for what they choose to call something.
-- the author recounting their OWN experience, reaction, or situational judgment ("it has been interesting to hear…", "we found it frustrating that…", "it has at times been necessary to challenge…", "I was surprised that…"). This is first-person experiential reportage, not an assertion about the world. See the experience-vs-claim rule below.
-- anything a reader accepts as reportage rather than argument
-
-The test, applied literally: would a skeptical reader stop and say "wait — is that true? prove it"? Write the "says who?" out against the sentence. If asking it would sound absurd to a human editor, the sentence is not a claim. Recounting that something happened is never a claim about whether it should have, or whether it is generally true.
-
-EXPERIENCE IS NOT A CLAIM. The same evaluative word can be a claim or just the author's experience — the difference is what it is predicated on.
-- Predicated on the WORLD = a claim: "this approach is the most effective", "the area is one of the most interesting" (asserts a property of the thing; contestable; flag if unsupported).
-- Predicated on the AUTHOR'S act of perceiving or doing = experience, NOT a claim: "it has been interesting to hear X", "it was necessary for us to challenge Y", "we found Z frustrating" (reports the author's own reaction or situational judgment; a reader cannot dispute what the author found; stay silent).
-The reliable structural tell for the silent case is the frame "it has been / it was [adjective] to [verb]" and other first-person experiential constructions. When you see an evaluative word, do not flag on the word — check whether it describes a property of the world or the author's own experience. Only the former is a claim.
-
-Hedge language is not the same as a claim. A hedge ("possibly", "could", "may", "might", "tends to") is the author signalling they are not banking on it. But a hedge does NOT make a sentence safe if a contestable proposition still sits underneath it. Test by stripping the hedge: "This area has POSSIBLY been one of the most interesting because it points to cultural values" still asserts, underneath, that the area is among the most interesting and names a reason — that is a real evaluative-causal claim and it qualifies. By contrast, if stripping the hedge leaves only a definition, reportage, or the author's own experience, stay silent. The rule: flag the proposition under the hedge if you can name it; if the only thing you can point at is the hedge word itself, there is no claim.
-
-STEP 2 — TYPE FILTER. Of the sentences that survive STEP 1, flag only those that are ALSO one of these kinds of assertion. These are claim-TYPES to recognize, never words to catch — the listed words are claims only when asserted about the world (STEP 1), not when they describe the author's own experience.
-- a causal explanation (X causes / leads to / drives Y, or "because…")
-- a broad generalization
-- an interpretation of what evidence means
-- a comparison, ranking, or superiority claim
-  · claim: "this is one of the most effective methods" (property of the method)
-  · NOT a claim: "it was one of the most interesting talks I attended" (author's experience)
-- an evaluative judgment about the world
-  · claim: "peer review is necessary for research integrity" (asserted as generally true)
-  · NOT a claim: "it has at times been necessary to challenge stakeholders" (author's own situational judgment)
-- a conclusion presented as established
-
-Both steps must pass. A sentence that is contestable but isn't one of these types, or is one of these types but is plain reportage or the author's own experience, does not get flagged.
-
-────────────────────────────────────────────────────────
-SUPPORT, NOT FIDELITY
-Your question is only: is this assertion backed by anything nearby? You are noticing the ABSENCE of support. You do NOT judge whether an existing citation faithfully supports the claim — that is a separate check. If support appears to be present nearby, stay silent.
-
-ONE SENTENCE CAN CARRY TWO CLAIMS — SPLIT, THEN PICK ONE.
-A sentence often welds an evaluation to a reason ("one of the most interesting BECAUSE it points to cultural values" = an evaluative claim + a causal claim). When this happens:
-- Identify the separate claims.
-- Choose the SINGLE load-bearing one — usually the one the rest of the paragraph leans on.
-- Set exact_text to just that claim's span, not the whole sentence.
-- Write the note about that ONE claim only. Never interrogate two propositions in a single note — that is what produces tangled, re-read-twice questions. One claim, one gap, one question.
-
-────────────────────────────────────────────────────────
-STEP 3 — THE NOTE. Only once a sentence has passed both steps, write the note this way.
-
-VOICE — a sharp peer who reads generously. Engaged, not cold; curious, not
-corrective. You point; you don't grade. The writing stays theirs.
-
-- Read generously first. Where it is cheap and TRUE, name what the sentence is
-  doing before you name the gap — but only in words specific to THIS sentence.
-  "This is the pivot the section turns on, so 'most interesting' resting on
-  assertion stands out — by whose measure?" The warmth is in taking the work
-  seriously, not in adjectives.
-
-- Warmth is stance, never padding. Banned openers — they are warm boilerplate
-  and fail the specificity test exactly like generic notes do: "Great point,
-  but…", "I love this — one thought…", "Nice work here…", "Just a small
-  thought…". If your opener would fit any sentence, cut it.
-
-- Genre sets how much room you take, not the character:
-  · scholarly — crisp and dry. These authors are being peer-reviewed; precision
-    IS the respect. Minimal framing, straight to the question.
-  · trade / essay — warmer, a little more room, the generous-reading clause
-    earns its place more often.
-  · fiction — warmest, craft-and-continuity register, softest touch.
-
-- Confidence sets the register. Use a light first person ONLY for honest
-  uncertainty ("I couldn't confirm this one", "I might be misreading"); never
-  for verdicts. The tool speaks as "I" when unsure and recedes to plain
-  statement when pointing at something solid.
-
-- Ask, don't rule. No verdicts, no rewrites, no emoji, no scold. One sentence.
-
-- Quote the exact words carrying the weight: "'a torrent of questionable results' — says who?" Point at the phrase, never at the remedy. Do not offer a menu of fixes.
-- Match the question to the kind of claim. For an EVALUATIVE claim, the gap is usually the measure or the perspective: "'one of the most interesting' — by whose measure? Reads as your judgment stated as a property." For a CAUSAL claim, the gap is the link: "'because it points to cultural values' — offered as the reason, but established or your read?" Do not reach for "says who?" by reflex when the real issue is an evaluation dressed as a fact.
-
-NAME THE GAP — the rule that decides whether the flag survives.
-The note must name the SPECIFIC thing the claim omits, asserts, or oversimplifies — not gesture at the existence of a gap. You must be able to state what is actually missing or contestable about THIS sentence.
-- Good (names the gap, one claim): "'one of the most interesting' — by whose measure?"
-- Bad (two claims tangled, gap not named): "'it points towards cultural values' — says who, and is that what makes 'one of the most interesting' true?"
-If the only thing you can do is point at a word and ask a generic "by what measure / under what conditions / says who" without being able to name the actual omitted thing, then you have not understood a real claim — drop the flag. (If "by what measure?" has no measure to point at because the sentence reports the author's own experience, that is the experience case from STEP 1 — it should never have reached here.) A note that cannot name the gap is a flag that should not fire.
-
-The specificity test, applied to your own note before returning it: would this note read identically on a different claim? If yes, it is not specific enough — rewrite it to name something only THIS sentence contains. Banned because they fit any sentence: "make it hold", "source it, soften it, or cut it", "what would make this stronger", "add support", "by what measure?" / "under what conditions?" with nothing named. Do not propose a rewritten sentence — ask, never rewrite. The writing stays theirs.
-
-────────────────────────────────────────────────────────
-OUTPUT
-Return fewer, better annotations. For each, JSON:
-- paragraph_id
-- exact_text          (the atomic span of the ONE chosen claim, verbatim)
-- annotation_type     "claim"
-- shape               short label for the claim type, used to cluster repeats (e.g. "causal", "generalization", "evaluative", "comparison")
-- justification       internal only — short reason this is a contestable, unsupported assertion about the world, naming the specific gap (for ranking; not shown to the author)
-- suggested_note      author-facing — the one-sentence question about ONE claim that names the gap and quotes the load-bearing phrase
-- severity            "minor" | "notable" | "significant"   (advisory only — nothing is ever blocked)
-- confidence          0.0–1.0
-
-If no sentence passes both steps, return an empty findings array. That is a valid and common result.
-
-Input paragraphs:
-{{PARAGRAPHS_JSON}}
-
-Return valid JSON only:
-{
-  "findings": []
-}`
-
-export const AUTO_FACT_CHECK_REVIEW_PROMPT = `You are reviewing manuscript paragraphs for one thing only: FACT-CHECK NEEDS — discrete factual statements that should be verified against an outside source.
-
-Not your job: argumentative claims, grammar, style, persuasiveness. You only decide whether a statement is a checkable fact that passes all the gates below.
-
-You DETECT; you do not VERIFY. Never state whether a fact is true or false, correct or incorrect. You mark what should be checked and leave it at status "Unverified". A separate verification pass settles it against sources.
-
-GENRE: {{GENRE}}   (scholarly | trade | essay | fiction)
-
-────────────────────────────────────────────────────────
-GATES. Run in order. A statement must pass ALL of them. Most statements will not. Silence is the correct, common outcome.
-
-GATE 0 — Is it a citation or reference?
-A reference-list entry, bibliography line, or inline citation (author-year, DOI, URL, bracketed number) is a pointer to a source, not an assertion about the world. Never fact-check it; it is out of scope here. If the span is or sits inside a citation, stay silent.
-
-GATE 1 — Is it about the world?
-The statement must assert something true or false independently of this manuscript. If its subject is the document itself — its sections, equations, tables, figures, examples, script, fixture, or the act of authoring it ("we add…", "this section shows…", "Equation 1 describes…", "the sample includes…") — it is NOT a fact check. First-person or self-referential authorial statements never qualify, no matter how concrete they sound.
-
-GATE 2 — Can you name the source that would settle it?
-You must be able to name the KIND of authoritative source a checker would consult: a standard, dated record, registry, dataset, named study, official policy, specification, publisher page, or archival document. If no such source exists or you cannot name one, it is not checkable — do not flag it. This is the gate that separates a real fact from a sentence that merely sounds factual.
-
-GATE 3 — Is it worth checking?
-Only flag statements a reader could reasonably doubt and that carry weight in the argument or the publication record. Skip the self-evident, trivial, incidental, and merely concrete. Concrete language alone is never a reason to flag.
-
-ATOMIC SPANS
-Flag only the checkable phrase, not the whole sentence. If a sentence contains one verifiable fact inside otherwise unflaggable prose, the span is just that fact (the date, figure, named event, attribution) — nothing extra.
-
-────────────────────────────────────────────────────────
-THE NOTE. Only once a statement has passed every gate, write the note this way.
-
-VOICE — a sharp peer who reads generously. Engaged, not cold; curious, not
-corrective. You point; you don't grade. The writing stays theirs.
-
-- Read generously first. Where it is cheap and TRUE, name what the sentence is
-  doing before you name the gap — but only in words specific to THIS sentence.
-  "This is the pivot the section turns on, so 'most interesting' resting on
-  assertion stands out — by whose measure?" The warmth is in taking the work
-  seriously, not in adjectives.
-
-- Warmth is stance, never padding. Banned openers — they are warm boilerplate
-  and fail the specificity test exactly like generic notes do: "Great point,
-  but…", "I love this — one thought…", "Nice work here…", "Just a small
-  thought…". If your opener would fit any sentence, cut it.
-
-- Genre sets how much room you take, not the character:
-  · scholarly — crisp and dry. These authors are being peer-reviewed; precision
-    IS the respect. Minimal framing, straight to the question.
-  · trade / essay — warmer, a little more room, the generous-reading clause
-    earns its place more often.
-  · fiction — warmest, craft-and-continuity register, softest touch.
-
-- Confidence sets the register. Use a light first person ONLY for honest
-  uncertainty ("I couldn't confirm this one", "I might be misreading"); never
-  for verdicts. The tool speaks as "I" when unsure and recedes to plain
-  statement when pointing at something solid.
-
-- Ask, don't rule. No verdicts, no rewrites, no emoji, no scold. One sentence.
-
-- Point at what to check, not a verdict: "The 2011 ship date — one for the changelog to confirm?" not "This date is wrong."
-- Quote the exact checkable words; never the category. "'40% reduction' — which study?" not "Concrete factual language may need verification."
-
-The specificity test, applied to your own note before returning it: would this note read identically on a different fact? If yes, it is not specific enough — name something only THIS statement contains. Banned because they fit any sentence: "verify against an authoritative source", "make it hold", "source it, soften it, or cut it". If the only note you can write is generic, the statement did not really pass the gates — drop it.
-
-────────────────────────────────────────────────────────
-OUTPUT
-Return fewer, better items. For each, JSON:
-- paragraph_id
-- exact_text          (the atomic checkable span, verbatim)
-- annotation_type     "fact_check"
-- shape               short label for clustering repeats (e.g. "date", "statistic", "named-event", "attribution")
-- justification       internal only — why it passes the gates, naming the external referent / source kind (for ranking; not shown to the author)
-- suggested_note      author-facing — the one-sentence question quoting the checkable phrase
-- severity            "minor" | "notable" | "significant"   (advisory only — nothing is ever blocked)
-- confidence          0.0–1.0
-
-If no statement passes every gate, return an empty findings array. That is a valid and common result.
-
-Input paragraphs:
-{{PARAGRAPHS_JSON}}
-
-Return valid JSON only:
-{
-  "findings": []
-}`
-
-export const AUTO_SOURCE_REVIEW_PROMPT = `You are reviewing manuscript paragraphs for one thing only: SOURCE checks —
-attributed claims whose accuracy depends on whether the CITED SOURCE actually
-supports them.
-
-You DETECT candidates; you do not VERIFY. Never state whether the source supports
-the claim. Mark it at status "Unverified". A downstream pass resolves the
-reference and checks fidelity.
-
-Not your job: claims about the world, facts, grammar, style.
-
-GENRE: {{GENRE}}
-
-────────────────────────────────────────────────────────
-STEP 1 — GATES. All must pass. Most sentences will not. Silence is common.
-
-GATE A — Is there a NAMED source attached to the claim?
-SOURCE fires only when a claim is attributed to a specific, identifiable source
-(author-year, a named report, a dated study, a titled work). If the sentence
-asserts something but names no source ("studies show", "it is well known",
-"experts agree"), that is phantom authority — NOT a SOURCE check. Stay silent;
-another check handles it.
-
-GATE B — Is it the claim, not the bare reference?
-A reference-list entry or a bare citation on its own is a pointer, not a claim.
-Flag only an attributed claim IN THE PROSE that asserts what a source found,
-showed, or established. Never flag the bibliography line itself.
-
-STEP 2 — CAPTURE THE PAIR.
-The span must contain BOTH the attributed claim and the source it points to, so
-the downstream check knows which reference to resolve and what to check against.
-
-────────────────────────────────────────────────────────
-STEP 3 — THE NOTE.
-
-VOICE — a careful peer, crisp and unaccusatory. This is the least personal check
-you run: it asks whether a citation is faithful, not whether the author's
-thinking is sound. Authors prefer it precise, not padded — precision reads as
-care, padding reads as suspicion. Stay dry. Do NOT add a generous-reading
-preamble; there is no argument to read generously, only a citation to confirm.
-
-- Point at what to confirm against the source — never a verdict.
-  "'Smith 2019 found a 40% drop' — does the paper report that figure, or a
-  smaller effect?"
-- Use first person ONLY for honest uncertainty, and use it where the resolved
-  source is thin: "I can only see the abstract here — does the full paper report
-  that 40%?" Naming the tool's own limit is the warmest, most trust-building
-  thing this check can do.
-- NAME THE GAP: name the specific attributed thing that needs confirming. If you
-  can't say what specifically should be checked, drop the flag. Banned generic:
-  "verify this citation", "check the source".
-- No verdicts, no rewrites, no emoji, no scold. One sentence.
-
-────────────────────────────────────────────────────────
-OUTPUT — for each finding, JSON:
-- paragraph_id
-- exact_text          (claim + source, verbatim)
-- annotation_type     "source"
-- shape               e.g. "attributed-figure", "attributed-finding", "paraphrase-of-source"
-- justification       internal only — why this is an attributed claim needing fidelity check, naming what to confirm
-- suggested_note      author-facing — the one-sentence question naming what to confirm against the source
-- severity            "minor" | "notable" | "significant"   (advisory only)
-- confidence          0.0–1.0
-
-Empty array if nothing passes.
-
-Input paragraphs:
-{{PARAGRAPHS_JSON}}
-
-Return valid JSON only:
-{ "findings": [] }`
-
-export const AUTO_COPYEDIT_REVIEW_PROMPT = `You are the COPYEDIT pass. You check manuscript paragraphs against external
-standards of correctness and clarity: grammar, spelling, punctuation, usage, and
-a supplied house style. You move the text TOWARD the standard.
-
-You are NOT the editorial checks (claims, facts, sources, logic) and you are NOT
-the voice check. Ignore substance and ignore whether the prose sounds like the
-author. You only catch what is wrong or genuinely ambiguous.
-
-You raise issues; you never auto-apply. Status is "Suggested" — the author
-accepts or dismisses.
-
-GENRE: {{GENRE}}
-HOUSE STYLE: {{HOUSE_STYLE}}   (a style sheet, or "none — use standard usage")
-
-────────────────────────────────────────────────────────
-GATE — Is it actually wrong, or genuinely ambiguous?
-Flag ONLY:
-- a grammar, spelling, or punctuation error
-- a usage error (wrong word, agreement, tense)
-- a house-style violation (only if a house style is supplied)
-- a genuine clarity break — a sentence ambiguous enough that a careful reader
-  would misread it, not merely a sentence you could phrase more smoothly
-
-STAY SILENT for preference. NEVER flag: "could be tighter", "consider varying
-sentence length", "this word is repeated", "this could be clearer", or any
-stylistic improvement to text that is already correct and unambiguous. If it is
-not wrong and not genuinely ambiguous, there is nothing to do. Most sentences are
-fine — be silent by default.
-
-────────────────────────────────────────────────────────
-THE SUGGESTION GRADIENT — this decides whether you offer a fix or only point.
-- MECHANICAL / UNCONTESTED (spelling, agreement, punctuation, clear house-style):
-  you MAY hand over the correction. The fix is not contested and not a matter of
-  voice. Example: "'its' → 'it's' (contraction of 'it is')."
-- CLARITY / AMBIGUITY: you ONLY point — never rewrite. Rewriting for clarity
-  shapes the author's prose, which is not your job. Example: "Two readings here —
-  does 'it' refer to the model or the dataset?"
-Rule: the more uncontested the fix, the freer the suggestion; the closer to
-shaping prose, the more you revert to pointing only.
-
-────────────────────────────────────────────────────────
-THE NOTE.
-Voice: crisp, plain, helpful. Terse is respectful here — this is correctness, not
-craft. One item per note.
-- Name the specific rule or the specific ambiguity. Never "this needs editing".
-- For mechanical fixes, the correction itself is the note.
-- For ambiguity, ask which reading is meant.
-- No praise, no padding, no scold, no emoji.
-
-────────────────────────────────────────────────────────
-OUTPUT — for each finding, JSON:
-- paragraph_id
-- exact_text          (the smallest span containing the error/ambiguity, verbatim)
-- annotation_type     "copyedit"
-- shape               e.g. "spelling", "agreement", "punctuation", "house-style", "ambiguity"
-- justification       internal only — the rule broken or the two readings
-- suggested_note      author-facing — the correction (mechanical) or the question (ambiguity)
-- severity            "minor" | "notable" | "significant"   (advisory only — nothing is enforced)
-- confidence          0.0–1.0
-
-Empty array if nothing is wrong or ambiguous. That is the common result on clean prose.
-
-Input paragraphs:
-{{PARAGRAPHS_JSON}}
-
-Return valid JSON only:
-{ "findings": [] }`
-
-export const AUTO_VOICE_REVIEW_PROMPT = `You are the VOICE check. You flag where the manuscript DEPARTS FROM THE AUTHOR'S
-OWN VOICE, as defined by a target profile built from samples of their writing.
-Your purpose is to protect the author from being flattened toward a generic mean
-— including the flattening that AI assistance produces.
-
-You are NOT the editorial checks and you are NOT copyedit. You do not judge
-correctness, substance, or whether the writing is GOOD. You judge only whether it
-sounds like THIS AUTHOR, in this register.
-
-You raise issues; you NEVER suggest a fix and NEVER rewrite. The fix is the
-voice; rewriting would perform the exact flattening you exist to prevent. You may
-only point. Status is "Needs review" — the author decides.
-
-GENRE / REGISTER: {{GENRE}}
-
-────────────────────────────────────────────────────────
-THE TARGET — what the author sounds like (built from their samples)
-{{VOICE_PROFILE}}
-
-This profile describes register/formality, sentence rhythm and its NATURAL
-VARIANCE, structural and paragraph habits, characteristic devices, diction level,
-and how the author opens, transitions, and closes — each with a TOLERANCE BAND
-showing how much the author legitimately varies.
-
-────────────────────────────────────────────────────────
-THE ABSOLUTE GATE — measure against the AUTHOR, never against your own taste.
-A finding is "this departs from the author's target voice." A finding is NEVER
-"I would write this differently" or "this could be better." If your reason for
-flagging is your own preference rather than a measurable departure from the
-profile, DROP IT. Surfacing your preference is forbidden — it is infinite noise
-and it pushes the author toward the mean, which is the one thing you must never
-do.
-
-A departure must exceed the tolerance band to count. Normal variation within the
-author's natural range is NOT a finding — flagging ordinary range is the most
-common failure. When unsure whether something is drift or just range, treat it
-as range and stay silent.
-
-────────────────────────────────────────────────────────
-WHAT TO FLAG (consistency, not quality)
-- register drift: the piece shifts formality mid-stream against its own baseline
-- tonal whiplash: e.g. dry throughout, then suddenly promotional
-- jargon spike: dense terminology against an otherwise plain voice (or vice versa)
-- SMOOTHING TOWARD THE GENERIC: the author's characteristic rhythm, devices, or
-  diction have flattened into competent-but-anonymous prose. THIS IS THE MOST
-  IMPORTANT CASE. Polished, fluent sentences that have lost the author's
-  fingerprints are exactly what to catch — fluency is not a reason to stay
-  silent. If a passage reads like any competent writer could have written it but
-  this author would not have, flag it.
-
-NEVER FLAG: correct-but-different-from-how-you'd-phrase-it; the author writing
-well; or a deliberate, sustained new move (that is the author evolving — see below).
-
-────────────────────────────────────────────────────────
-THE NOTE — point only, name the specific departure.
-- Name what shifted, relative to the author's voice, as a question:
-  "This reads flatter and more generic than your usual rhythm here — yours, or
-  smoothed?"
-  "Shifts more formal than the rest of the chapter — intended?"
-- NEVER hand over rewritten words. NEVER suggest "try…". You point; they decide.
-- NAME THE GAP: name the specific feature that departed (rhythm, register,
-  diction, a lost device). If you can only say "this feels off" without naming
-  what, drop it.
-- Use first person for honest uncertainty: "I might be misreading your range here".
-- No praise, no scold, no emoji. One sentence.
-
-────────────────────────────────────────────────────────
-AUTHOR EVOLUTION
-A single sentence that differs is drift; a sustained, deliberate new pattern is
-the author's voice CHANGING, which is legitimate and not a fault. Do not flag a
-consistent new move as if it were an error. (When the author dismisses a voice
-flag, the system widens the tolerance — so a dismissed flag should not recur.)
-
-────────────────────────────────────────────────────────
-CONFIDENCE / DEGRADATION
-- Profile built from 3–5 matched samples: normal confidence.
-- Profile built from 1–2 samples, or thin: LOW confidence — flag far fewer
-  things, only clear departures, and say the read is tentative.
-- If the manuscript's register has no matching sample in the profile, say so and
-  flag nothing rather than guessing — like admitting a source check has only an
-  abstract.
-
-────────────────────────────────────────────────────────
-OUTPUT — for each finding, JSON:
-- paragraph_id
-- exact_text          (the span that departs, verbatim)
-- annotation_type     "voice"
-- shape               e.g. "register-drift", "tonal-whiplash", "jargon-spike", "smoothed-generic"
-- justification       internal only — the specific feature that departed and by how much vs the tolerance band
-- suggested_note      author-facing — points at the departure, never a fix
-- severity            "minor" | "notable" | "significant"   (advisory only)
-- confidence          0.0–1.0
-
-Bias toward an empty array. Most of a manuscript that sounds like its author should produce nothing. The flags should cluster where the voice flattened, not spread evenly.
-
-Input paragraphs:
-{{PARAGRAPHS_JSON}}
-
-Return valid JSON only:
-{ "findings": [] }`
-
-export const AUTO_THREAD_REVIEW_PROMPT = `You are detecting THREADS — promises the text makes to the reader that may go
-unkept.
-
-Two stages. You are the DETECTOR: you find the PROMISE from the text in front of
-you. You do NOT assert the payoff is missing — a retrieval step confirms absence
-before the flag is shown.
-
-GENRE: {{GENRE}}
-
-────────────────────────────────────────────────────────
-GATE — Is this a real promise to the reader?
-Flag:
-- forward references: "as we will see in chapter 6", "we return to this below",
-  "more on this shortly"
-- under-delivered enumerations: "for three reasons" / "two things" where the
-  count may not be met
-- explicit setups: a question or topic raised as central and flagged for later
-  treatment
-Stay silent for rhetorical filler that promises nothing specific ("as is well
-known", "of course"), and for promises already paid off in the SAME paragraph.
-
-────────────────────────────────────────────────────────
-THE NOTE.
-
-VOICE — a helpful peer, the warmest register in the system. This is the note
-authors LIKE: it catches something they would want caught, so it reads as
-service, not criticism. Keep it light and collegial. A light first person lands
-especially well here — you are a reader who went looking, not an auditor.
-
-- Phrase as a question, never an accusation.
-  "You point ahead to 'chapter 6' here — does the payoff land there?"
-  "'For three reasons' — I can find two; is one missing?"
-  "I went looking for where this gets answered and didn't spot it — is it later?"
-- NAME THE GAP: name the specific promise (the chapter, the count, the topic).
-  Generic "this is unresolved" → drop.
-- No emoji, no scold. One sentence.
-
-────────────────────────────────────────────────────────
-OUTPUT — for each finding, JSON:
-- paragraph_id
-- exact_text          (the promise span, verbatim)
-- annotation_type     "thread"
-- shape               e.g. "forward-ref", "enumeration-shortfall", "unanswered-setup"
-- justification       internal only — what was promised; the retrieval step adjusts for whether it's kept
-- suggested_note      author-facing — names the promise, asks if it's kept
-- severity            "minor" | "notable" | "significant"   (advisory only)
-- confidence          0.0–1.0   (how clearly a promise was made; retrieval adjusts for kept/unkept)
-
-Empty array if no real promise is made.
-
-Input paragraphs:
-{{PARAGRAPHS_JSON}}
-
-Return valid JSON only:
-{ "findings": [] }`
-
-export const AUTO_CONFLICT_REVIEW_PROMPT = `You are checking whether a passage CONTRADICTS another part of the same
-manuscript. You are given a target span and passages retrieved from elsewhere in
-the document.
-
-You DETECT contradictions; you do not resolve them. Status is "Needs support" —
-the author reconciles.
-
-GENRE: {{GENRE}}
-
-────────────────────────────────────────────────────────
-GATE — Is it a genuine contradiction?
-Flag ONLY when the target and a retrieved passage cannot both be true as written:
-a number, date, name, quantity, definition, or continuity detail that disagrees.
-Stay silent for:
-- restatement, emphasis, or the same point made twice
-- a view the author intentionally develops or revises across the work
-- apparent tension where both statements can hold (different scope, time, or case)
-- retrieved passages that merely share a topic but assert nothing conflicting
-
-The test: name the specific fact in each passage and confirm they are
-incompatible. If you cannot state both sides as a flat disagreement, there is no
-contradiction — stay silent.
-
-────────────────────────────────────────────────────────
-THE NOTE.
-
-VOICE — a careful peer, NEUTRAL about which side is right. This is the most
-delicate note in the system, because pointing at a contradiction can imply
-carelessness. The warmth here is NOT padding — it is neutrality. Never imply the
-author made a mistake. Present both sides flat, as two things that drifted, and
-trust the author to know which holds.
-
-- Name both values, ask which holds — never assert which is wrong.
-  "Ch.2 says 400 participants; here it's 450 — which holds?"
-  NOT "This contradicts your earlier figure" (accusatory, assumes error).
-- Locate both passages so the author can reconcile.
-- Use first person lightly only for genuine uncertainty about the match
-  ("these may be measuring different things — same population?").
-- NAME THE GAP: if you can't name the two conflicting values, drop it. Banned:
-  "this is inconsistent", "contradiction found".
-- No verdicts on which is correct, no rewrites, no emoji. One sentence.
-
-────────────────────────────────────────────────────────
-OUTPUT — for each finding, JSON:
-- paragraph_id
-- exact_text          (the target span, verbatim)
-- annotation_type     "conflict"
-- shape               e.g. "number-mismatch", "definition-drift", "continuity"
-- justification       internal only — both conflicting values and where each appears
-- suggested_note      author-facing — names both sides, asks which holds
-- severity            "minor" | "notable" | "significant"   (advisory only)
-- confidence          0.0–1.0
-
-Empty array if nothing genuinely conflicts.
-
-Target span: {{TARGET_SPAN}}
-Retrieved passages: {{RETRIEVED_PASSAGES}}
-
-Return valid JSON only:
-{ "findings": [] }`
-
-export const AUTO_LOGIC_REVIEW_PROMPT = `You are detecting LOGIC gaps — a conclusion that does not follow from the grounds
-the author gives for it (a missing warrant between reason and claim).
-
-This is the most conservative check you run. False positives make the tool feel
-like it is arguing with the author. Flag ONLY clear, high-confidence gaps. When
-in doubt — which is often — stay silent.
-
-You DETECT; the author resolves. Status "Needs support".
-
-GENRE: {{GENRE}}
-
-────────────────────────────────────────────────────────
-GATE — Is there a real gap a reasonable reader would stop at?
-Flag only when the stated grounds genuinely do not license the conclusion drawn
-from them, and a careful reader would ask "wait, how did you get from there to
-there?" Stay silent for:
-- a step that is compressed or unstated but obvious to recover
-- the author's reasoned judgment, even if you'd weigh it differently
-- a conclusion the surrounding text actually does support
-- mere style, ordering, or emphasis
-
-Test: can you name the SPECIFIC missing step between the reason and the
-conclusion? If you cannot state the exact link that's absent, there is no gap to
-flag — stay silent.
-
-────────────────────────────────────────────────────────
-THE NOTE.
-
-VOICE — a generous peer who assumes you know your own argument. This check
-questions the author's REASONING, the most exposing thing to question, so it
-carries the heaviest warmth and the strongest assumption of competence. The key
-move: assume the missing step EXISTS in the author's head and ask them to
-surface it. Treat the gap as unstated, never as absent. That is the difference
-between a peer and a critic.
-
-- Read the reasoning generously, then ask for the link — framed as implicit, not
-  missing:
-  "Cost falls here, then adoption rises — is there a link you're holding
-  implicit, or is the jump intended?"
-  NOT "This doesn't follow" (asserts absence, reads as a verdict on their
-  thinking).
-- The "holding implicit / intended?" framing assumes the author has the step and
-  simply didn't write it. Use it.
-- Use first person for your own uncertainty: "I might be missing a step between
-  these two — is it stated somewhere?"
-- NAME THE GAP: name the absent link specifically. Never "this doesn't follow"
-  with nothing named. Ask, don't rule. No rewrites, no emoji.
-
-────────────────────────────────────────────────────────
-OUTPUT — for each finding, JSON:
-- paragraph_id
-- exact_text          (the conclusion + its grounds, verbatim)
-- annotation_type     "logic"
-- shape               e.g. "missing-warrant", "non-sequitur", "unsupported-leap"
-- justification       internal only — name the specific missing step between grounds and conclusion
-- suggested_note      author-facing — names the link, frames it as implicit, asks
-- severity            "minor" | "notable" | "significant"   (advisory only)
-- confidence          0.0–1.0
-
-Bias HARD toward an empty array — most paragraphs have no real logic gap.
-
-Input paragraphs:
-{{PARAGRAPHS_JSON}}
-
-Return valid JSON only:
-{ "findings": [] }`
-
-export interface AutoReviewParagraph {
-  id: string
-  text: string
-  from: number
-  to: number
-}
-
-export type AutoReviewPromptKind =
-  | 'claim'
-  | 'fact-check'
-  | 'source'
-  | 'thread'
-  | 'conflict'
-  | 'logic'
-  | 'copyedit'
-  | 'voice'
-export type AutoReviewFindingSeverity =
-  | 'info'
-  | 'warning'
-  | 'blocking'
-  | 'minor'
-  | 'notable'
-  | 'significant'
-export type EditorialAnnotationType =
-  | 'claim'
-  | 'fact-check'
-  | 'source'
-  | 'thread'
-  | 'conflict'
-  | 'logic'
-  | 'copyedit'
-  | 'voice'
-export type EditorialProcess =
-  | 'claims'
-  | 'fact-checks'
-  | 'claims-and-facts'
-  | 'source'
-  | 'source-and-thread'
-  | 'thread'
-  | 'conflict'
-  | 'logic'
-  | 'logic-and-conflict'
-  | 'full-editorial'
-  | 'copyedit'
-  | 'voice'
-export type EditorialGenreMode =
-  | 'infer'
-  | 'fiction'
-  | 'essay-opinion'
-  | 'scholarly'
-export type EditorialStrictness = 'low' | 'medium' | 'high'
-export type EditorialDensity = 'sparse' | 'normal'
-export type EditorialScope = 'local' | 'document'
-
-export interface EditorialFrameworkEntry {
-  type: EditorialAnnotationType
-  label: string
-  question: string
-  meaning: string
-  openStatus: 'open' | 'needs-support' | 'unverified' | 'suggested' | 'needs-review'
-  closedStatuses: string[]
-  color: 'amber' | 'red' | 'blue' | 'violet' | 'slate' | 'green' | 'pink'
-  resolver: string
-  disabledReason?: string
-}
-
-export const EDITORIAL_FRAMEWORK: Record<
-  EditorialAnnotationType,
-  EditorialFrameworkEntry
-> = {
-  claim: {
-    type: 'claim',
-    label: 'Claim',
-    question: 'Says who?',
-    meaning:
-      'An assertion the author advances that is not backed in the manuscript.',
-    openStatus: 'needs-support',
-    closedStatuses: ['resolved'],
-    color: 'amber',
-    resolver: 'author',
-  },
-  'fact-check': {
-    type: 'fact-check',
-    label: 'Fact check',
-    question: 'What source settles this?',
-    meaning:
-      'An external, source-settled statement whose truth does not depend on this manuscript.',
-    openStatus: 'unverified',
-    closedStatuses: ['verified', 'disputed'],
-    color: 'red',
-    resolver: 'verifier',
-  },
-  source: {
-    type: 'source',
-    label: 'Source',
-    question: 'Does the source say this?',
-    meaning:
-      'An attributed claim whose accuracy depends on whether the cited source supports it.',
-    openStatus: 'unverified',
-    closedStatuses: ['verified', 'disputed'],
-    color: 'blue',
-    resolver: 'source checker',
-  },
-  thread: {
-    type: 'thread',
-    label: 'Thread',
-    question: 'Where is the payoff?',
-    meaning:
-      'A promise to the reader, such as a forward reference, setup, or enumeration.',
-    openStatus: 'open',
-    closedStatuses: ['supported', 'rejected'],
-    color: 'violet',
-    resolver: 'author',
-  },
-  conflict: {
-    type: 'conflict',
-    label: 'Conflict',
-    question: 'Does this contradict elsewhere?',
-    meaning:
-      'A possible contradiction between two manuscript passages; requires retrieval before release.',
-    openStatus: 'needs-support',
-    closedStatuses: ['supported', 'rejected'],
-    color: 'slate',
-    resolver: 'author',
-    disabledReason: 'Requires internal retrieval before it can run.',
-  },
-  logic: {
-    type: 'logic',
-    label: 'Logic',
-    question: 'How does this follow?',
-    meaning:
-      'A sparse, opt-in check for clear reasoning gaps or missing warrants.',
-    openStatus: 'needs-support',
-    closedStatuses: ['supported', 'rejected'],
-    color: 'slate',
-    resolver: 'author',
-  },
-  copyedit: {
-    type: 'copyedit',
-    label: 'Copyedit',
-    question: 'What needs correcting?',
-    meaning:
-      'A correctness, usage, punctuation, or house-style issue that should be suggested but not auto-applied.',
-    openStatus: 'suggested',
-    closedStatuses: ['supported', 'rejected'],
-    color: 'green',
-    resolver: 'author',
-  },
-  voice: {
-    type: 'voice',
-    label: 'Voice',
-    question: 'Does this still sound like the author?',
-    meaning:
-      'A possible drift from the supplied author voice profile, especially smoothing toward generic prose.',
-    openStatus: 'needs-review',
-    closedStatuses: ['supported', 'rejected'],
-    color: 'pink',
-    resolver: 'author',
-  },
-}
-
-export function enabledEditorialTypesForProcess(
-  process: EditorialProcess = 'claims-and-facts',
-): EditorialAnnotationType[] {
-  if (process === 'claims') return ['claim']
-  if (process === 'fact-checks') return ['fact-check']
-  if (process === 'source') return ['source']
-  if (process === 'source-and-thread') return ['source', 'thread']
-  if (process === 'thread') return ['thread']
-  if (process === 'logic') return ['logic']
-  if (process === 'copyedit') return ['copyedit']
-  if (process === 'voice') return ['voice']
-  if (process === 'logic-and-conflict') return ['logic']
-  if (process === 'conflict') return []
-  if (process === 'full-editorial') {
-    return ['claim', 'fact-check', 'source', 'thread']
-  }
-  return ['claim', 'fact-check']
-}
-
-export interface AutoReviewFindingInput {
-  paragraph_id: string
-  exact_text: string
-  annotation_type:
-    | 'claim'
-    | 'fact_check'
-    | 'fact-check'
-    | 'source'
-    | 'thread'
-    | 'conflict'
-    | 'logic'
-    | 'copyedit'
-    | 'copy-edit'
-    | 'copy_edit'
-    | 'copyediting'
-    | 'copy-editing'
-    | 'voice'
-  shape?: string
-  subject?: string
-  justification?: string
-  suggested_note?: string
-  severity?: AutoReviewFindingSeverity
-  confidence?: number
-}
-
-export interface AutoReviewFindingResponse {
-  findings?: AutoReviewFindingInput[]
-  annotations?: AutoReviewFindingInput[]
-  items?: AutoReviewFindingInput[]
-  results?: AutoReviewFindingInput[]
-}
-
-export interface ValidatedAutoReviewFinding {
-  paragraphId: string
-  exactText: string
-  annotationType: CommentType
-  subject: string
-  note: string
-  severity: CommentSeverity
-  confidence: number
-  from: number
-  to: number
-}
-
-export interface AppliedAutoReviewFinding extends ValidatedAutoReviewFinding {
-  commentId: string
-}
-
-export interface AutoReviewFindingsProviderRequest {
-  paragraphs: AutoReviewParagraph[]
-  options: RunAutoReviewOptions
-}
-
-export type AutoReviewFindingsProvider = (
-  request: AutoReviewFindingsProviderRequest,
-) => Promise<AutoReviewFindingInput[]>
-
-export interface ApplyAutoReviewFindingsOptions {
-  author?: string
-  createdAt?: string
-  minConfidence?: number
-  idPrefix?: string
-}
-
-export interface RunAutoReviewOptions extends ApplyAutoReviewFindingsOptions {
-  process?: EditorialProcess
-  enabledTypes?: EditorialAnnotationType[]
-  genreMode?: EditorialGenreMode
-  strictness?: EditorialStrictness
-  density?: EditorialDensity
-  scope?: EditorialScope
-  maxFindings?: number
-  houseStyle?: string
-  voiceProfile?: string
-  signal?: AbortSignal
-  findingsProvider?: AutoReviewFindingsProvider
-  onProgress?: (result: RunAutoReviewResult) => void
-}
-
-export interface RunAutoReviewResult {
-  paragraphCount: number
-  findingCount: number
-  applied: AppliedAutoReviewFinding[]
-  skipped: number
-  unavailableReason?: string
-}
-
-export interface CopyAutoReviewPromptsResult {
-  copied: boolean
-  paragraphCount: number
-}
-
-declare module '@tiptap/core' {
-  interface Commands<ReturnType> {
-    autoReviewPrompts: {
-      applyAutoReviewFindings: (
-        paragraphs: AutoReviewParagraph[],
-        findings: AutoReviewFindingInput[],
-        options?: ApplyAutoReviewFindingsOptions,
-      ) => ReturnType
-    }
-  }
-}
-
-export const AutoReviewPrompts = Extension.create({
-  name: 'autoReviewPrompts',
-
-  addCommands() {
-    return {
-      applyAutoReviewFindings:
-        (paragraphs, findings, options) =>
-        ({ editor }) =>
-          applyAutoReviewFindings(editor, paragraphs, findings, options).applied
-            .length > 0,
-    }
-  },
-})
-
-export function collectAutoReviewParagraphs(
-  editor: Editor,
-): AutoReviewParagraph[] {
-  const paragraphs: AutoReviewParagraph[] = []
-  editor.state.doc.descendants((node, pos) => {
-    if (node.type.name !== 'paragraph') return true
-    if (isAutoReviewProtectedPosition(editor, pos + 1)) return false
-    const text = node.textContent.replace(/\s+/g, ' ').trim()
-    if (!text) return true
-    paragraphs.push({
-      id: `p-${paragraphs.length + 1}`,
-      text,
-      from: pos + 1,
-      to: pos + node.nodeSize - 1,
-    })
-    return false
-  })
-  return paragraphs
-}
-
-export function collectScopedAutoReviewParagraphs(
-  editor: Editor,
-  scope: EditorialScope = 'document',
-): AutoReviewParagraph[] {
-  const paragraphs = collectAutoReviewParagraphs(editor)
-  const { empty, from, to } = editor.state.selection
-  if (scope !== 'local' || empty) return paragraphs
-  return paragraphs.filter(
-    paragraph => paragraph.to >= from && paragraph.from <= to,
-  )
-}
-
-export function buildAutoReviewPrompt(
-  kind: AutoReviewPromptKind,
-  paragraphs: AutoReviewParagraph[],
-): string {
-  const payload = paragraphs.map(({ id, text }) => ({ id, text }))
-  const template = autoReviewPromptTemplate(kind)
-  return template.replace(
-    '{{PARAGRAPHS_JSON}}',
-    JSON.stringify(payload, null, 2),
-  )
-}
-
-export function buildAutoReviewPromptBundle(
-  paragraphs: AutoReviewParagraph[],
-): string {
-  return [
-    '# Claim detection prompt',
-    buildAutoReviewPrompt('claim', paragraphs),
-    '',
-    '# Fact-check detection prompt',
-    buildAutoReviewPrompt('fact-check', paragraphs),
-    '',
-    '# Source detection prompt',
-    buildAutoReviewPrompt('source', paragraphs),
-    '',
-    '# Thread detection prompt',
-    buildAutoReviewPrompt('thread', paragraphs),
-    '',
-    '# Logic detection prompt',
-    buildAutoReviewPrompt('logic', paragraphs),
-    '',
-    '# Copyedit prompt',
-    buildAutoReviewPrompt('copyedit', paragraphs),
-    '',
-    '# Voice prompt',
-    buildAutoReviewPrompt('voice', paragraphs),
-  ].join('\n\n')
-}
-
-export async function copyAutoReviewPromptsToClipboard(
-  editor: Editor,
-): Promise<CopyAutoReviewPromptsResult> {
-  const paragraphs = collectAutoReviewParagraphs(editor)
-  if (!paragraphs.length) return { copied: false, paragraphCount: 0 }
-  await navigator.clipboard.writeText(buildAutoReviewPromptBundle(paragraphs))
-  return { copied: true, paragraphCount: paragraphs.length }
-}
-
-export function parseAutoReviewFindingResponse(
-  value: string,
-): AutoReviewFindingInput[] {
-  const parsed = JSON.parse(value) as unknown
-  return normalizeAutoReviewFindingResponse(parsed)
-}
-
-export function validateAutoReviewFindings(
-  paragraphs: AutoReviewParagraph[],
-  findings: AutoReviewFindingInput[],
-  options: Pick<ApplyAutoReviewFindingsOptions, 'minConfidence'> = {},
-): ValidatedAutoReviewFinding[] {
-  const minConfidence = options.minConfidence ?? 0.55
-  const paragraphsById = new Map(
-    paragraphs.map(paragraph => [paragraph.id, paragraph]),
-  )
-  const occupied = new Set<string>()
-  const validated: ValidatedAutoReviewFinding[] = []
-
-  for (const rawFinding of findings) {
-    const finding = normalizeAutoReviewFinding(rawFinding)
-    if (!finding) continue
-    const paragraph = paragraphsById.get(finding.paragraph_id)
-    if (!paragraph) continue
-    const exactText = normalizeFindingText(finding.exact_text)
-    if (!exactText) continue
-    const confidence =
-      typeof finding.confidence === 'number' &&
-      Number.isFinite(finding.confidence)
-        ? finding.confidence
-        : 1
-    if (confidence < minConfidence) continue
-    const match = findAutoReviewSpan(paragraph.text, exactText)
-    if (!match) continue
-
-    const annotationType = normalizeAutoReviewAnnotationType(
-      finding.annotation_type,
-    )
-    if (!annotationType) continue
-    const key = `${paragraph.id}:${match.index}:${exactText}:${annotationType}`
-    if (occupied.has(key)) continue
-    occupied.add(key)
-
-    const from = paragraph.from + match.index
-    validated.push({
-      paragraphId: paragraph.id,
-      exactText: match.text,
-      annotationType,
-      subject:
-        normalizeFindingText(finding.subject) ||
-        normalizeFindingText(finding.shape) ||
-        match.text,
-      note: buildFindingNote(finding),
-      severity: normalizeFindingSeverity(finding.severity),
-      confidence,
-      from,
-      to: from + match.text.length,
-    })
-  }
-
-  return preferFactChecksForDuplicateSpans(validated)
-}
-
-export function applyAutoReviewFindings(
-  editor: Editor,
-  paragraphs: AutoReviewParagraph[],
-  findings: AutoReviewFindingInput[],
-  options: ApplyAutoReviewFindingsOptions = {},
-): { applied: AppliedAutoReviewFinding[]; skipped: number } {
-  const validated = validateAutoReviewFindings(paragraphs, findings, options)
-  const now = options.createdAt ?? new Date().toISOString()
-  const applied: AppliedAutoReviewFinding[] = []
-
-  validated.forEach((finding, index) => {
-    if (rangeHasAutoReviewMark(editor, finding)) return
-    const id = [
-      options.idPrefix ?? 'auto-review',
-      finding.annotationType,
-      now.replace(/\W+/g, '-'),
-      index + 1,
-    ].join('-')
-    const appliedMark = applyCommentMarkToRange(
-      editor,
-      finding.from,
-      finding.to,
-      {
-        commentId: id,
-        commentText: finding.note,
-        commentType: finding.annotationType,
-        subjectText: finding.exactText,
-        author: options.author ?? 'Auto review',
-        createdAt: now,
-        reviewStatus: defaultAutoReviewStatus(finding.annotationType),
-        severity: finding.severity,
-      },
-      { scrollIntoView: false, focusEditor: false },
-    )
-    if (appliedMark) applied.push({ ...finding, commentId: id })
-  })
-
-  return { applied, skipped: findings.length - applied.length }
-}
-
-export async function runAutoReview(
-  editor: Editor,
-  options: RunAutoReviewOptions = {},
-): Promise<RunAutoReviewResult> {
-  const paragraphs = collectScopedAutoReviewParagraphs(editor, options.scope)
-  options.onProgress?.({
-    paragraphCount: paragraphs.length,
-    findingCount: 0,
-    applied: [],
-    skipped: 0,
-  })
-  if (!options.findingsProvider) {
-    return {
-      paragraphCount: paragraphs.length,
-      findingCount: 0,
-      applied: [],
-      skipped: 0,
-      unavailableReason: 'Editorial review provider is not configured.',
-    }
-  }
-  const findings = await options.findingsProvider({ paragraphs, options })
-  const result = applyAutoReviewFindings(editor, paragraphs, findings, {
-    ...options,
-    author: options.author ?? 'Auto review',
-    idPrefix: options.idPrefix ?? 'auto-review',
-  })
-  const runResult = {
-    paragraphCount: paragraphs.length,
-    findingCount: findings.length,
-    applied: result.applied,
-    skipped: result.skipped,
-  }
-  options.onProgress?.(runResult)
-  return runResult
-}
-
-function normalizeAutoReviewAnnotationType(
-  value: AutoReviewFindingInput['annotation_type'] | string | undefined,
-): EditorialAnnotationType | null {
-  const normalized = normalizeFindingText(value).toLowerCase()
-  if (normalized === 'claim') return 'claim'
-  if (
-    normalized === 'fact_check' ||
-    normalized === 'fact-check' ||
-    normalized === 'fact check' ||
-    normalized === 'factcheck'
-  ) {
-    return 'fact-check'
-  }
-  if (
-    normalized === 'source' ||
-    normalized === 'thread' ||
-    normalized === 'conflict' ||
-    normalized === 'logic' ||
-    normalized === 'voice'
-  ) {
-    return normalized
-  }
-  if (
-    normalized === 'copyedit' ||
-    normalized === 'copy-edit' ||
-    normalized === 'copy edit' ||
-    normalized === 'copy_edit' ||
-    normalized === 'copyediting' ||
-    normalized === 'copy-editing'
-  ) {
-    return 'copyedit'
-  }
-  return null
-}
-
-function autoReviewPromptTemplate(kind: AutoReviewPromptKind): string {
-  switch (kind) {
-    case 'claim':
-      return AUTO_CLAIM_REVIEW_PROMPT
-    case 'fact-check':
-      return AUTO_FACT_CHECK_REVIEW_PROMPT
-    case 'source':
-      return AUTO_SOURCE_REVIEW_PROMPT
-    case 'thread':
-      return AUTO_THREAD_REVIEW_PROMPT
-    case 'conflict':
-      return AUTO_CONFLICT_REVIEW_PROMPT
-    case 'logic':
-      return AUTO_LOGIC_REVIEW_PROMPT
-    case 'copyedit':
-      return AUTO_COPYEDIT_REVIEW_PROMPT
-    case 'voice':
-      return AUTO_VOICE_REVIEW_PROMPT
-  }
-}
-
-function defaultAutoReviewStatus(
-  annotationType: CommentType,
-): CommentReviewStatus {
-  if (annotationType === 'fact-check' || annotationType === 'source') {
-    return 'unverified'
-  }
-  if (annotationType === 'thread') return 'open'
-  if (annotationType === 'copyedit') return 'suggested'
-  if (annotationType === 'voice') return 'needs-review'
-  return 'needs-support'
-}
-
-function normalizeFindingText(value: string | undefined): string {
-  return typeof value === 'string' ? value.replace(/\s+/g, ' ').trim() : ''
-}
-
-function normalizeAutoReviewFindingResponse(
-  value: unknown,
-): AutoReviewFindingInput[] {
-  const candidates = Array.isArray(value)
-    ? value
-    : value && typeof value === 'object'
-    ? (['findings', 'annotations', 'items', 'results'] as const).reduce<
-        unknown[]
-      >((result, key) => {
-        if (result.length) return result
-        const candidate = (value as AutoReviewFindingResponse)[key]
-        return Array.isArray(candidate) ? candidate : result
-      }, [])
-    : []
-
-  return candidates
-    .map(candidate => normalizeAutoReviewFinding(candidate))
-    .filter((finding): finding is AutoReviewFindingInput => finding !== null)
-}
-
-function normalizeAutoReviewFinding(
-  value: unknown,
-): AutoReviewFindingInput | null {
-  if (!value || typeof value !== 'object') return null
-  const record = value as Record<string, unknown>
-  const paragraphId = firstString(
-    record.paragraph_id,
-    record.paragraphId,
-    record.paragraph,
-    record.id,
-  )
-  const exactText = firstString(
-    record.exact_text,
-    record.exactText,
-    record.span,
-    record.text,
-    record.quote,
-  )
-  const annotationType = firstString(
-    record.annotation_type,
-    record.annotationType,
-    record.type,
-    record.kind,
-  )
-  if (!paragraphId || !exactText || !annotationType) return null
-  const normalizedAnnotationType =
-    normalizeAutoReviewAnnotationType(annotationType)
-  if (!normalizedAnnotationType) return null
-  const confidence =
-    typeof record.confidence === 'number' && Number.isFinite(record.confidence)
-      ? record.confidence
-      : typeof record.score === 'number' && Number.isFinite(record.score)
-      ? record.score
-      : undefined
-  const severity = firstString(record.severity) as
-    | AutoReviewFindingSeverity
-    | undefined
-
-  return {
-    paragraph_id: paragraphId,
-    exact_text: exactText,
-    annotation_type:
-      normalizedAnnotationType === 'fact-check'
-        ? 'fact_check'
-        : normalizedAnnotationType,
-    shape: firstString(record.shape, record.category),
-    subject: firstString(record.subject),
-    justification: firstString(record.justification, record.reason),
-    suggested_note: firstString(
-      record.suggested_note,
-      record.suggestedNote,
-      record.note,
-      record.comment,
-    ),
-    severity,
-    confidence,
-  }
-}
-
-function firstString(...values: unknown[]): string | undefined {
-  for (const value of values) {
-    if (typeof value === 'string' && value.trim()) return value
-  }
-  return undefined
-}
-
-function findAutoReviewSpan(
-  paragraphText: string,
-  exactText: string,
-): { index: number; text: string } | null {
-  const directIndex = paragraphText.indexOf(exactText)
-  if (directIndex >= 0) {
-    return { index: directIndex, text: exactText }
-  }
-
-  const foldedParagraph = foldAutoReviewTextWithMap(paragraphText)
-  const foldedExact = foldAutoReviewText(exactText)
-  if (!foldedExact) return null
-  const foldedIndex = foldedParagraph.text.indexOf(foldedExact)
-  if (foldedIndex < 0) return null
-  const start = foldedParagraph.map[foldedIndex]
-  const lastFoldedIndex = foldedIndex + foldedExact.length - 1
-  const end =
-    (foldedParagraph.map[lastFoldedIndex] ?? start) +
-    (paragraphText[foldedParagraph.map[lastFoldedIndex] ?? start]?.length ?? 1)
-  return { index: start, text: paragraphText.slice(start, end) }
-}
-
-function foldAutoReviewText(value: string): string {
-  return foldAutoReviewTextWithMap(value).text
-}
-
-function foldAutoReviewTextWithMap(value: string): {
-  text: string
-  map: number[]
-} {
-  let text = ''
-  const map: number[] = []
-  let previousWasSpace = true
-  for (let index = 0; index < value.length; index += 1) {
-    const folded = foldAutoReviewChar(value[index] ?? '')
-    if (!folded) continue
-    if (/\s/.test(folded)) {
-      if (previousWasSpace) continue
-      text += ' '
-      map.push(index)
-      previousWasSpace = true
-      continue
-    }
-    text += folded
-    map.push(index)
-    previousWasSpace = false
-  }
-  return {
-    text: text.trimEnd(),
-    map: map.slice(0, text.trimEnd().length),
-  }
-}
-
-function foldAutoReviewChar(char: string): string {
-  if (char === '“' || char === '”') return '"'
-  if (char === '‘' || char === '’') return "'"
-  if (char === '–' || char === '—') return '-'
-  if (char === '…') return '.'
-  return char.toLowerCase()
-}
-
-function normalizeFindingSeverity(
-  value: AutoReviewFindingSeverity | undefined,
-): CommentSeverity {
-  if (value === 'blocking') return 'blocking'
-  if (value === 'warning' || value === 'notable' || value === 'significant') {
-    return 'advisory'
-  }
-  return 'note'
-}
-
-function buildFindingNote(finding: AutoReviewFindingInput): string {
-  const suggested = normalizeFindingText(finding.suggested_note)
-  const justification = normalizeFindingText(finding.justification)
-  return suggested || justification || 'Review this passage.'
-}
-
-function preferFactChecksForDuplicateSpans(
-  findings: ValidatedAutoReviewFinding[],
-): ValidatedAutoReviewFinding[] {
-  const bySpan = new Map<string, ValidatedAutoReviewFinding>()
-  for (const finding of findings) {
-    const key = `${finding.from}:${finding.to}:${finding.exactText}`
-    const existing = bySpan.get(key)
-    if (
-      !existing ||
-      (existing.annotationType === 'claim' &&
-        finding.annotationType === 'fact-check')
-    ) {
-      bySpan.set(key, finding)
-    }
-  }
-  return Array.from(bySpan.values())
-}
-
-function rangeHasAutoReviewMark(
-  editor: Editor,
-  finding: ValidatedAutoReviewFinding,
-): boolean {
-  let found = false
-  editor.state.doc.nodesBetween(finding.from, finding.to, node => {
-    if (found || !node.isText) return !found
-    found = node.marks.some(
-      mark =>
-        mark.type.name === 'commentMark' &&
-        mark.attrs.commentType === finding.annotationType &&
-        mark.attrs.subjectText === finding.exactText,
-    )
-    return !found
-  })
-  return found
-}
-
-function isAutoReviewProtectedPosition(editor: Editor, pos: number): boolean {
-  try {
-    const dom = editor.view.domAtPos(pos).node
-    const element = dom instanceof HTMLElement ? dom : dom.parentElement
-    return Boolean(
-      element?.closest(
-        [
-          '[contenteditable="false"]',
-          'cite.ps-citation',
-          '[data-pm-reference-entry="true"]',
-          '[data-pm-generated-references="true"]',
-          '[data-pm-references-empty="true"]',
-        ].join(','),
-      ),
-    )
-  } catch {
-    return false
-  }
-}
+import { Extension, type Editor } from '@tiptap/core'
+import {
+  applyCommentMarkToRange,
+  type CommentReviewStatus,
+  type CommentSeverity,
+  type CommentType,
+} from '../commentUtils.js'
+
+export const AUTO_CLAIM_REVIEW_PROMPT = `You are reviewing manuscript paragraphs for one thing only: CLAIMS — statements the author advances as true that a reader could reasonably doubt and ask "says who?" of.
+
+Not your job: fact-checking, grammar, style, citations. Those are handled elsewhere. You only decide whether a sentence makes a contestable assertion that may need support, and if so, leave one short note.
+
+GENRE: {{GENRE}}   (scholarly | trade | essay | fiction)
+
+────────────────────────────────────────────────────────
+STEP 1 — GATES. Run these first. A sentence must pass ALL of them to be eligible. Most sentences will not. Being silent is the correct, common outcome.
+
+GATE A — Is it a citation or reference?
+A reference-list entry, bibliography line, or inline citation (author-year, DOI, URL, bracketed number) is a pointer to a source, not a claim about the world. Never flag it; it is out of scope here. If the span is or sits inside a citation, stay silent.
+
+GATE B — Is it a contestable assertion about the world?
+This is the decisive gate. Most prose is not a claim. Stay silent if the sentence is:
+- narration or recounting of events ("Ryan created the documentation", "the group met and discussed")
+- description of a process or procedure (steps, what happens, who does what)
+- a statement of intent or sequence ("after X was agreed, Y would happen")
+- the author defining their own terms, notation, or labels — INCLUDING when the naming move uses a hedge verb. "We represent this as PR", "for our purposes Z means…", "traditional publishing could be described as RP", "this can be called the review stage", "we might label this X" are ALL definitions, not claims. A hedge word ("could", "might", "can be") in front of a naming move does not turn a definition into a contestable assertion. The author owes no evidence for what they choose to call something.
+- the author recounting their OWN experience, reaction, or situational judgment ("it has been interesting to hear…", "we found it frustrating that…", "it has at times been necessary to challenge…", "I was surprised that…"). This is first-person experiential reportage, not an assertion about the world. See the experience-vs-claim rule below.
+- anything a reader accepts as reportage rather than argument
+
+The test, applied literally: would a skeptical reader stop and say "wait — is that true? prove it"? Write the "says who?" out against the sentence. If asking it would sound absurd to a human editor, the sentence is not a claim. Recounting that something happened is never a claim about whether it should have, or whether it is generally true.
+
+EXPERIENCE IS NOT A CLAIM. The same evaluative word can be a claim or just the author's experience — the difference is what it is predicated on.
+- Predicated on the WORLD = a claim: "this approach is the most effective", "the area is one of the most interesting" (asserts a property of the thing; contestable; flag if unsupported).
+- Predicated on the AUTHOR'S act of perceiving or doing = experience, NOT a claim: "it has been interesting to hear X", "it was necessary for us to challenge Y", "we found Z frustrating" (reports the author's own reaction or situational judgment; a reader cannot dispute what the author found; stay silent).
+The reliable structural tell for the silent case is the frame "it has been / it was [adjective] to [verb]" and other first-person experiential constructions. When you see an evaluative word, do not flag on the word — check whether it describes a property of the world or the author's own experience. Only the former is a claim.
+
+Hedge language is not the same as a claim. A hedge ("possibly", "could", "may", "might", "tends to") is the author signalling they are not banking on it. But a hedge does NOT make a sentence safe if a contestable proposition still sits underneath it. Test by stripping the hedge: "This area has POSSIBLY been one of the most interesting because it points to cultural values" still asserts, underneath, that the area is among the most interesting and names a reason — that is a real evaluative-causal claim and it qualifies. By contrast, if stripping the hedge leaves only a definition, reportage, or the author's own experience, stay silent. The rule: flag the proposition under the hedge if you can name it; if the only thing you can point at is the hedge word itself, there is no claim.
+
+STEP 2 — TYPE FILTER. Of the sentences that survive STEP 1, flag only those that are ALSO one of these kinds of assertion. These are claim-TYPES to recognize, never words to catch — the listed words are claims only when asserted about the world (STEP 1), not when they describe the author's own experience.
+- a causal explanation (X causes / leads to / drives Y, or "because…")
+- a broad generalization
+- an interpretation of what evidence means
+- a comparison, ranking, or superiority claim
+  · claim: "this is one of the most effective methods" (property of the method)
+  · NOT a claim: "it was one of the most interesting talks I attended" (author's experience)
+- an evaluative judgment about the world
+  · claim: "peer review is necessary for research integrity" (asserted as generally true)
+  · NOT a claim: "it has at times been necessary to challenge stakeholders" (author's own situational judgment)
+- a conclusion presented as established
+
+Both steps must pass. A sentence that is contestable but isn't one of these types, or is one of these types but is plain reportage or the author's own experience, does not get flagged.
+
+────────────────────────────────────────────────────────
+SUPPORT, NOT FIDELITY
+Your question is only: is this assertion backed by anything nearby? You are noticing the ABSENCE of support. You do NOT judge whether an existing citation faithfully supports the claim — that is a separate check. If support appears to be present nearby, stay silent.
+
+ONE SENTENCE CAN CARRY TWO CLAIMS — SPLIT, THEN PICK ONE.
+A sentence often welds an evaluation to a reason ("one of the most interesting BECAUSE it points to cultural values" = an evaluative claim + a causal claim). When this happens:
+- Identify the separate claims.
+- Choose the SINGLE load-bearing one — usually the one the rest of the paragraph leans on.
+- Set exact_text to just that claim's span, not the whole sentence.
+- Write the note about that ONE claim only. Never interrogate two propositions in a single note — that is what produces tangled, re-read-twice questions. One claim, one gap, one question.
+
+────────────────────────────────────────────────────────
+STEP 3 — THE NOTE. Only once a sentence has passed both steps, write the note this way.
+
+VOICE — a sharp peer who reads generously. Engaged, not cold; curious, not
+corrective. You point; you don't grade. The writing stays theirs.
+
+- Read generously first. Where it is cheap and TRUE, name what the sentence is
+  doing before you name the gap — but only in words specific to THIS sentence.
+  "This is the pivot the section turns on, so 'most interesting' resting on
+  assertion stands out — by whose measure?" The warmth is in taking the work
+  seriously, not in adjectives.
+
+- Warmth is stance, never padding. Banned openers — they are warm boilerplate
+  and fail the specificity test exactly like generic notes do: "Great point,
+  but…", "I love this — one thought…", "Nice work here…", "Just a small
+  thought…". If your opener would fit any sentence, cut it.
+
+- Genre sets how much room you take, not the character:
+  · scholarly — crisp and dry. These authors are being peer-reviewed; precision
+    IS the respect. Minimal framing, straight to the question.
+  · trade / essay — warmer, a little more room, the generous-reading clause
+    earns its place more often.
+  · fiction — warmest, craft-and-continuity register, softest touch.
+
+- Confidence sets the register. Use a light first person ONLY for honest
+  uncertainty ("I couldn't confirm this one", "I might be misreading"); never
+  for verdicts. The tool speaks as "I" when unsure and recedes to plain
+  statement when pointing at something solid.
+
+- Ask, don't rule. No verdicts, no rewrites, no emoji, no scold. One sentence.
+
+- Quote the exact words carrying the weight: "'a torrent of questionable results' — says who?" Point at the phrase, never at the remedy. Do not offer a menu of fixes.
+- Match the question to the kind of claim. For an EVALUATIVE claim, the gap is usually the measure or the perspective: "'one of the most interesting' — by whose measure? Reads as your judgment stated as a property." For a CAUSAL claim, the gap is the link: "'because it points to cultural values' — offered as the reason, but established or your read?" Do not reach for "says who?" by reflex when the real issue is an evaluation dressed as a fact.
+
+NAME THE GAP — the rule that decides whether the flag survives.
+The note must name the SPECIFIC thing the claim omits, asserts, or oversimplifies — not gesture at the existence of a gap. You must be able to state what is actually missing or contestable about THIS sentence.
+- Good (names the gap, one claim): "'one of the most interesting' — by whose measure?"
+- Bad (two claims tangled, gap not named): "'it points towards cultural values' — says who, and is that what makes 'one of the most interesting' true?"
+If the only thing you can do is point at a word and ask a generic "by what measure / under what conditions / says who" without being able to name the actual omitted thing, then you have not understood a real claim — drop the flag. (If "by what measure?" has no measure to point at because the sentence reports the author's own experience, that is the experience case from STEP 1 — it should never have reached here.) A note that cannot name the gap is a flag that should not fire.
+
+The specificity test, applied to your own note before returning it: would this note read identically on a different claim? If yes, it is not specific enough — rewrite it to name something only THIS sentence contains. Banned because they fit any sentence: "make it hold", "source it, soften it, or cut it", "what would make this stronger", "add support", "by what measure?" / "under what conditions?" with nothing named. Do not propose a rewritten sentence — ask, never rewrite. The writing stays theirs.
+
+────────────────────────────────────────────────────────
+OUTPUT
+Return fewer, better annotations. For each, JSON:
+- paragraph_id
+- exact_text          (the atomic span of the ONE chosen claim, verbatim)
+- annotation_type     "claim"
+- shape               short label for the claim type, used to cluster repeats (e.g. "causal", "generalization", "evaluative", "comparison")
+- justification       internal only — short reason this is a contestable, unsupported assertion about the world, naming the specific gap (for ranking; not shown to the author)
+- suggested_note      author-facing — the one-sentence question about ONE claim that names the gap and quotes the load-bearing phrase
+- severity            "minor" | "notable" | "significant"   (advisory only — nothing is ever blocked)
+- confidence          0.0–1.0
+
+If no sentence passes both steps, return an empty findings array. That is a valid and common result.
+
+Input paragraphs:
+{{PARAGRAPHS_JSON}}
+
+Return valid JSON only:
+{
+  "findings": []
+}`
+
+export const AUTO_FACT_CHECK_REVIEW_PROMPT = `You are reviewing manuscript paragraphs for one thing only: FACT-CHECK NEEDS — discrete factual statements that should be verified against an outside source.
+
+Not your job: argumentative claims, grammar, style, persuasiveness. You only decide whether a statement is a checkable fact that passes all the gates below.
+
+You DETECT; you do not VERIFY. Never state whether a fact is true or false, correct or incorrect. You mark what should be checked and leave it at status "Unverified". A separate verification pass settles it against sources.
+
+GENRE: {{GENRE}}   (scholarly | trade | essay | fiction)
+
+────────────────────────────────────────────────────────
+GATES. Run in order. A statement must pass ALL of them. Most statements will not. Silence is the correct, common outcome.
+
+GATE 0 — Is it a citation or reference?
+A reference-list entry, bibliography line, or inline citation (author-year, DOI, URL, bracketed number) is a pointer to a source, not an assertion about the world. Never fact-check it; it is out of scope here. If the span is or sits inside a citation, stay silent.
+
+GATE 1 — Is it about the world?
+The statement must assert something true or false independently of this manuscript. If its subject is the document itself — its sections, equations, tables, figures, examples, script, fixture, or the act of authoring it ("we add…", "this section shows…", "Equation 1 describes…", "the sample includes…") — it is NOT a fact check. First-person or self-referential authorial statements never qualify, no matter how concrete they sound.
+
+GATE 2 — Can you name the source that would settle it?
+You must be able to name the KIND of authoritative source a checker would consult: a standard, dated record, registry, dataset, named study, official policy, specification, publisher page, or archival document. If no such source exists or you cannot name one, it is not checkable — do not flag it. This is the gate that separates a real fact from a sentence that merely sounds factual.
+
+GATE 3 — Is it worth checking?
+Only flag statements a reader could reasonably doubt and that carry weight in the argument or the publication record. Skip the self-evident, trivial, incidental, and merely concrete. Concrete language alone is never a reason to flag.
+
+ATOMIC SPANS
+Flag only the checkable phrase, not the whole sentence. If a sentence contains one verifiable fact inside otherwise unflaggable prose, the span is just that fact (the date, figure, named event, attribution) — nothing extra.
+
+────────────────────────────────────────────────────────
+THE NOTE. Only once a statement has passed every gate, write the note this way.
+
+VOICE — a sharp peer who reads generously. Engaged, not cold; curious, not
+corrective. You point; you don't grade. The writing stays theirs.
+
+- Read generously first. Where it is cheap and TRUE, name what the sentence is
+  doing before you name the gap — but only in words specific to THIS sentence.
+  "This is the pivot the section turns on, so 'most interesting' resting on
+  assertion stands out — by whose measure?" The warmth is in taking the work
+  seriously, not in adjectives.
+
+- Warmth is stance, never padding. Banned openers — they are warm boilerplate
+  and fail the specificity test exactly like generic notes do: "Great point,
+  but…", "I love this — one thought…", "Nice work here…", "Just a small
+  thought…". If your opener would fit any sentence, cut it.
+
+- Genre sets how much room you take, not the character:
+  · scholarly — crisp and dry. These authors are being peer-reviewed; precision
+    IS the respect. Minimal framing, straight to the question.
+  · trade / essay — warmer, a little more room, the generous-reading clause
+    earns its place more often.
+  · fiction — warmest, craft-and-continuity register, softest touch.
+
+- Confidence sets the register. Use a light first person ONLY for honest
+  uncertainty ("I couldn't confirm this one", "I might be misreading"); never
+  for verdicts. The tool speaks as "I" when unsure and recedes to plain
+  statement when pointing at something solid.
+
+- Ask, don't rule. No verdicts, no rewrites, no emoji, no scold. One sentence.
+
+- Point at what to check, not a verdict: "The 2011 ship date — one for the changelog to confirm?" not "This date is wrong."
+- Quote the exact checkable words; never the category. "'40% reduction' — which study?" not "Concrete factual language may need verification."
+
+The specificity test, applied to your own note before returning it: would this note read identically on a different fact? If yes, it is not specific enough — name something only THIS statement contains. Banned because they fit any sentence: "verify against an authoritative source", "make it hold", "source it, soften it, or cut it". If the only note you can write is generic, the statement did not really pass the gates — drop it.
+
+────────────────────────────────────────────────────────
+OUTPUT
+Return fewer, better items. For each, JSON:
+- paragraph_id
+- exact_text          (the atomic checkable span, verbatim)
+- annotation_type     "fact_check"
+- shape               short label for clustering repeats (e.g. "date", "statistic", "named-event", "attribution")
+- justification       internal only — why it passes the gates, naming the external referent / source kind (for ranking; not shown to the author)
+- suggested_note      author-facing — the one-sentence question quoting the checkable phrase
+- severity            "minor" | "notable" | "significant"   (advisory only — nothing is ever blocked)
+- confidence          0.0–1.0
+
+If no statement passes every gate, return an empty findings array. That is a valid and common result.
+
+Input paragraphs:
+{{PARAGRAPHS_JSON}}
+
+Return valid JSON only:
+{
+  "findings": []
+}`
+
+export const AUTO_SOURCE_REVIEW_PROMPT = `You are reviewing manuscript paragraphs for one thing only: SOURCE checks —
+attributed claims whose accuracy depends on whether the CITED SOURCE actually
+supports them.
+
+You DETECT candidates; you do not VERIFY. Never state whether the source supports
+the claim. Mark it at status "Unverified". A downstream pass resolves the
+reference and checks fidelity.
+
+Not your job: claims about the world, facts, grammar, style.
+
+GENRE: {{GENRE}}
+
+────────────────────────────────────────────────────────
+STEP 1 — GATES. All must pass. Most sentences will not. Silence is common.
+
+GATE A — Is there a NAMED source attached to the claim?
+SOURCE fires only when a claim is attributed to a specific, identifiable source
+(author-year, a named report, a dated study, a titled work). If the sentence
+asserts something but names no source ("studies show", "it is well known",
+"experts agree"), that is phantom authority — NOT a SOURCE check. Stay silent;
+another check handles it.
+
+GATE B — Is it the claim, not the bare reference?
+A reference-list entry or a bare citation on its own is a pointer, not a claim.
+Flag only an attributed claim IN THE PROSE that asserts what a source found,
+showed, or established. Never flag the bibliography line itself.
+
+STEP 2 — CAPTURE THE PAIR.
+The span must contain BOTH the attributed claim and the source it points to, so
+the downstream check knows which reference to resolve and what to check against.
+
+────────────────────────────────────────────────────────
+STEP 3 — THE NOTE.
+
+VOICE — a careful peer, crisp and unaccusatory. This is the least personal check
+you run: it asks whether a citation is faithful, not whether the author's
+thinking is sound. Authors prefer it precise, not padded — precision reads as
+care, padding reads as suspicion. Stay dry. Do NOT add a generous-reading
+preamble; there is no argument to read generously, only a citation to confirm.
+
+- Point at what to confirm against the source — never a verdict.
+  "'Smith 2019 found a 40% drop' — does the paper report that figure, or a
+  smaller effect?"
+- Use first person ONLY for honest uncertainty, and use it where the resolved
+  source is thin: "I can only see the abstract here — does the full paper report
+  that 40%?" Naming the tool's own limit is the warmest, most trust-building
+  thing this check can do.
+- NAME THE GAP: name the specific attributed thing that needs confirming. If you
+  can't say what specifically should be checked, drop the flag. Banned generic:
+  "verify this citation", "check the source".
+- No verdicts, no rewrites, no emoji, no scold. One sentence.
+
+────────────────────────────────────────────────────────
+OUTPUT — for each finding, JSON:
+- paragraph_id
+- exact_text          (claim + source, verbatim)
+- annotation_type     "source"
+- shape               e.g. "attributed-figure", "attributed-finding", "paraphrase-of-source"
+- justification       internal only — why this is an attributed claim needing fidelity check, naming what to confirm
+- suggested_note      author-facing — the one-sentence question naming what to confirm against the source
+- severity            "minor" | "notable" | "significant"   (advisory only)
+- confidence          0.0–1.0
+
+Empty array if nothing passes.
+
+Input paragraphs:
+{{PARAGRAPHS_JSON}}
+
+Return valid JSON only:
+{ "findings": [] }`
+
+export const AUTO_COPYEDIT_REVIEW_PROMPT = `You are the COPYEDIT pass. You check manuscript paragraphs against external
+standards of correctness and clarity: grammar, spelling, punctuation, usage, and
+a supplied house style. You move the text TOWARD the standard.
+
+You are NOT the editorial checks (claims, facts, sources, logic) and you are NOT
+the voice check. Ignore substance and ignore whether the prose sounds like the
+author. You only catch what is wrong or genuinely ambiguous.
+
+You raise issues; you never auto-apply. Status is "Suggested" — the author
+accepts or dismisses.
+
+GENRE: {{GENRE}}
+HOUSE STYLE: {{HOUSE_STYLE}}   (a style sheet, or "none — use standard usage")
+
+────────────────────────────────────────────────────────
+GATE — Is it actually wrong, or genuinely ambiguous?
+Flag ONLY:
+- a grammar, spelling, or punctuation error
+- a usage error (wrong word, agreement, tense)
+- a house-style violation (only if a house style is supplied)
+- a genuine clarity break — a sentence ambiguous enough that a careful reader
+  would misread it, not merely a sentence you could phrase more smoothly
+
+STAY SILENT for preference. NEVER flag: "could be tighter", "consider varying
+sentence length", "this word is repeated", "this could be clearer", or any
+stylistic improvement to text that is already correct and unambiguous. If it is
+not wrong and not genuinely ambiguous, there is nothing to do. Most sentences are
+fine — be silent by default.
+
+────────────────────────────────────────────────────────
+THE SUGGESTION GRADIENT — this decides whether you offer a fix or only point.
+- MECHANICAL / UNCONTESTED (spelling, agreement, punctuation, clear house-style):
+  you MAY hand over the correction. The fix is not contested and not a matter of
+  voice. Example: "'its' → 'it's' (contraction of 'it is')."
+- CLARITY / AMBIGUITY: you ONLY point — never rewrite. Rewriting for clarity
+  shapes the author's prose, which is not your job. Example: "Two readings here —
+  does 'it' refer to the model or the dataset?"
+Rule: the more uncontested the fix, the freer the suggestion; the closer to
+shaping prose, the more you revert to pointing only.
+
+────────────────────────────────────────────────────────
+THE NOTE.
+Voice: crisp, plain, helpful. Terse is respectful here — this is correctness, not
+craft. One item per note.
+- Name the specific rule or the specific ambiguity. Never "this needs editing".
+- For mechanical fixes, the correction itself is the note.
+- For ambiguity, ask which reading is meant.
+- No praise, no padding, no scold, no emoji.
+
+────────────────────────────────────────────────────────
+OUTPUT — for each finding, JSON:
+- paragraph_id
+- exact_text          (the smallest span containing the error/ambiguity, verbatim)
+- annotation_type     "copyedit"
+- shape               e.g. "spelling", "agreement", "punctuation", "house-style", "ambiguity"
+- justification       internal only — the rule broken or the two readings
+- suggested_note      author-facing — the correction (mechanical) or the question (ambiguity)
+- severity            "minor" | "notable" | "significant"   (advisory only — nothing is enforced)
+- confidence          0.0–1.0
+
+Empty array if nothing is wrong or ambiguous. That is the common result on clean prose.
+
+Input paragraphs:
+{{PARAGRAPHS_JSON}}
+
+Return valid JSON only:
+{ "findings": [] }`
+
+export const AUTO_VOICE_REVIEW_PROMPT = `You are the VOICE check. You flag where the manuscript DEPARTS FROM THE AUTHOR'S
+OWN VOICE, as defined by a target profile built from samples of their writing.
+Your purpose is to protect the author from being flattened toward a generic mean
+— including the flattening that AI assistance produces.
+
+You are NOT the editorial checks and you are NOT copyedit. You do not judge
+correctness, substance, or whether the writing is GOOD. You judge only whether it
+sounds like THIS AUTHOR, in this register.
+
+You raise issues; you NEVER suggest a fix and NEVER rewrite. The fix is the
+voice; rewriting would perform the exact flattening you exist to prevent. You may
+only point. Status is "Needs review" — the author decides.
+
+GENRE / REGISTER: {{GENRE}}
+
+────────────────────────────────────────────────────────
+THE TARGET — what the author sounds like (built from their samples)
+{{VOICE_PROFILE}}
+
+This profile describes register/formality, sentence rhythm and its NATURAL
+VARIANCE, structural and paragraph habits, characteristic devices, diction level,
+and how the author opens, transitions, and closes — each with a TOLERANCE BAND
+showing how much the author legitimately varies.
+
+────────────────────────────────────────────────────────
+THE ABSOLUTE GATE — measure against the AUTHOR, never against your own taste.
+A finding is "this departs from the author's target voice." A finding is NEVER
+"I would write this differently" or "this could be better." If your reason for
+flagging is your own preference rather than a measurable departure from the
+profile, DROP IT. Surfacing your preference is forbidden — it is infinite noise
+and it pushes the author toward the mean, which is the one thing you must never
+do.
+
+A departure must exceed the tolerance band to count. Normal variation within the
+author's natural range is NOT a finding — flagging ordinary range is the most
+common failure. When unsure whether something is drift or just range, treat it
+as range and stay silent.
+
+────────────────────────────────────────────────────────
+WHAT TO FLAG (consistency, not quality)
+- register drift: the piece shifts formality mid-stream against its own baseline
+- tonal whiplash: e.g. dry throughout, then suddenly promotional
+- jargon spike: dense terminology against an otherwise plain voice (or vice versa)
+- SMOOTHING TOWARD THE GENERIC: the author's characteristic rhythm, devices, or
+  diction have flattened into competent-but-anonymous prose. THIS IS THE MOST
+  IMPORTANT CASE. Polished, fluent sentences that have lost the author's
+  fingerprints are exactly what to catch — fluency is not a reason to stay
+  silent. If a passage reads like any competent writer could have written it but
+  this author would not have, flag it.
+
+NEVER FLAG: correct-but-different-from-how-you'd-phrase-it; the author writing
+well; or a deliberate, sustained new move (that is the author evolving — see below).
+
+────────────────────────────────────────────────────────
+THE NOTE — point only, name the specific departure.
+- Name what shifted, relative to the author's voice, as a question:
+  "This reads flatter and more generic than your usual rhythm here — yours, or
+  smoothed?"
+  "Shifts more formal than the rest of the chapter — intended?"
+- NEVER hand over rewritten words. NEVER suggest "try…". You point; they decide.
+- NAME THE GAP: name the specific feature that departed (rhythm, register,
+  diction, a lost device). If you can only say "this feels off" without naming
+  what, drop it.
+- Use first person for honest uncertainty: "I might be misreading your range here".
+- No praise, no scold, no emoji. One sentence.
+
+────────────────────────────────────────────────────────
+AUTHOR EVOLUTION
+A single sentence that differs is drift; a sustained, deliberate new pattern is
+the author's voice CHANGING, which is legitimate and not a fault. Do not flag a
+consistent new move as if it were an error. (When the author dismisses a voice
+flag, the system widens the tolerance — so a dismissed flag should not recur.)
+
+────────────────────────────────────────────────────────
+CONFIDENCE / DEGRADATION
+- Profile built from 3–5 matched samples: normal confidence.
+- Profile built from 1–2 samples, or thin: LOW confidence — flag far fewer
+  things, only clear departures, and say the read is tentative.
+- If the manuscript's register has no matching sample in the profile, say so and
+  flag nothing rather than guessing — like admitting a source check has only an
+  abstract.
+
+────────────────────────────────────────────────────────
+OUTPUT — for each finding, JSON:
+- paragraph_id
+- exact_text          (the span that departs, verbatim)
+- annotation_type     "voice"
+- shape               e.g. "register-drift", "tonal-whiplash", "jargon-spike", "smoothed-generic"
+- justification       internal only — the specific feature that departed and by how much vs the tolerance band
+- suggested_note      author-facing — points at the departure, never a fix
+- severity            "minor" | "notable" | "significant"   (advisory only)
+- confidence          0.0–1.0
+
+Bias toward an empty array. Most of a manuscript that sounds like its author should produce nothing. The flags should cluster where the voice flattened, not spread evenly.
+
+Input paragraphs:
+{{PARAGRAPHS_JSON}}
+
+Return valid JSON only:
+{ "findings": [] }`
+
+export const AUTO_THREAD_REVIEW_PROMPT = `You are detecting THREADS — promises the text makes to the reader that may go
+unkept.
+
+Two stages. You are the DETECTOR: you find the PROMISE from the text in front of
+you. You do NOT assert the payoff is missing — a retrieval step confirms absence
+before the flag is shown.
+
+GENRE: {{GENRE}}
+
+────────────────────────────────────────────────────────
+GATE — Is this a real promise to the reader?
+Flag:
+- forward references: "as we will see in chapter 6", "we return to this below",
+  "more on this shortly"
+- under-delivered enumerations: "for three reasons" / "two things" where the
+  count may not be met
+- explicit setups: a question or topic raised as central and flagged for later
+  treatment
+Stay silent for rhetorical filler that promises nothing specific ("as is well
+known", "of course"), and for promises already paid off in the SAME paragraph.
+
+────────────────────────────────────────────────────────
+THE NOTE.
+
+VOICE — a helpful peer, the warmest register in the system. This is the note
+authors LIKE: it catches something they would want caught, so it reads as
+service, not criticism. Keep it light and collegial. A light first person lands
+especially well here — you are a reader who went looking, not an auditor.
+
+- Phrase as a question, never an accusation.
+  "You point ahead to 'chapter 6' here — does the payoff land there?"
+  "'For three reasons' — I can find two; is one missing?"
+  "I went looking for where this gets answered and didn't spot it — is it later?"
+- NAME THE GAP: name the specific promise (the chapter, the count, the topic).
+  Generic "this is unresolved" → drop.
+- No emoji, no scold. One sentence.
+
+────────────────────────────────────────────────────────
+OUTPUT — for each finding, JSON:
+- paragraph_id
+- exact_text          (the promise span, verbatim)
+- annotation_type     "thread"
+- shape               e.g. "forward-ref", "enumeration-shortfall", "unanswered-setup"
+- justification       internal only — what was promised; the retrieval step adjusts for whether it's kept
+- suggested_note      author-facing — names the promise, asks if it's kept
+- severity            "minor" | "notable" | "significant"   (advisory only)
+- confidence          0.0–1.0   (how clearly a promise was made; retrieval adjusts for kept/unkept)
+
+Empty array if no real promise is made.
+
+Input paragraphs:
+{{PARAGRAPHS_JSON}}
+
+Return valid JSON only:
+{ "findings": [] }`
+
+export const AUTO_CONFLICT_REVIEW_PROMPT = `You are checking whether a passage CONTRADICTS another part of the same
+manuscript. You are given a target span and passages retrieved from elsewhere in
+the document.
+
+You DETECT contradictions; you do not resolve them. Status is "Needs support" —
+the author reconciles.
+
+GENRE: {{GENRE}}
+
+────────────────────────────────────────────────────────
+GATE — Is it a genuine contradiction?
+Flag ONLY when the target and a retrieved passage cannot both be true as written:
+a number, date, name, quantity, definition, or continuity detail that disagrees.
+Stay silent for:
+- restatement, emphasis, or the same point made twice
+- a view the author intentionally develops or revises across the work
+- apparent tension where both statements can hold (different scope, time, or case)
+- retrieved passages that merely share a topic but assert nothing conflicting
+
+The test: name the specific fact in each passage and confirm they are
+incompatible. If you cannot state both sides as a flat disagreement, there is no
+contradiction — stay silent.
+
+────────────────────────────────────────────────────────
+THE NOTE.
+
+VOICE — a careful peer, NEUTRAL about which side is right. This is the most
+delicate note in the system, because pointing at a contradiction can imply
+carelessness. The warmth here is NOT padding — it is neutrality. Never imply the
+author made a mistake. Present both sides flat, as two things that drifted, and
+trust the author to know which holds.
+
+- Name both values, ask which holds — never assert which is wrong.
+  "Ch.2 says 400 participants; here it's 450 — which holds?"
+  NOT "This contradicts your earlier figure" (accusatory, assumes error).
+- Locate both passages so the author can reconcile.
+- Use first person lightly only for genuine uncertainty about the match
+  ("these may be measuring different things — same population?").
+- NAME THE GAP: if you can't name the two conflicting values, drop it. Banned:
+  "this is inconsistent", "contradiction found".
+- No verdicts on which is correct, no rewrites, no emoji. One sentence.
+
+────────────────────────────────────────────────────────
+OUTPUT — for each finding, JSON:
+- paragraph_id
+- exact_text          (the target span, verbatim)
+- annotation_type     "conflict"
+- shape               e.g. "number-mismatch", "definition-drift", "continuity"
+- justification       internal only — both conflicting values and where each appears
+- suggested_note      author-facing — names both sides, asks which holds
+- severity            "minor" | "notable" | "significant"   (advisory only)
+- confidence          0.0–1.0
+
+Empty array if nothing genuinely conflicts.
+
+Target span: {{TARGET_SPAN}}
+Retrieved passages: {{RETRIEVED_PASSAGES}}
+
+Return valid JSON only:
+{ "findings": [] }`
+
+export const AUTO_LOGIC_REVIEW_PROMPT = `You are detecting LOGIC gaps — a conclusion that does not follow from the grounds
+the author gives for it (a missing warrant between reason and claim).
+
+This is the most conservative check you run. False positives make the tool feel
+like it is arguing with the author. Flag ONLY clear, high-confidence gaps. When
+in doubt — which is often — stay silent.
+
+You DETECT; the author resolves. Status "Needs support".
+
+GENRE: {{GENRE}}
+
+────────────────────────────────────────────────────────
+GATE — Is there a real gap a reasonable reader would stop at?
+Flag only when the stated grounds genuinely do not license the conclusion drawn
+from them, and a careful reader would ask "wait, how did you get from there to
+there?" Stay silent for:
+- a step that is compressed or unstated but obvious to recover
+- the author's reasoned judgment, even if you'd weigh it differently
+- a conclusion the surrounding text actually does support
+- mere style, ordering, or emphasis
+
+Test: can you name the SPECIFIC missing step between the reason and the
+conclusion? If you cannot state the exact link that's absent, there is no gap to
+flag — stay silent.
+
+────────────────────────────────────────────────────────
+THE NOTE.
+
+VOICE — a generous peer who assumes you know your own argument. This check
+questions the author's REASONING, the most exposing thing to question, so it
+carries the heaviest warmth and the strongest assumption of competence. The key
+move: assume the missing step EXISTS in the author's head and ask them to
+surface it. Treat the gap as unstated, never as absent. That is the difference
+between a peer and a critic.
+
+- Read the reasoning generously, then ask for the link — framed as implicit, not
+  missing:
+  "Cost falls here, then adoption rises — is there a link you're holding
+  implicit, or is the jump intended?"
+  NOT "This doesn't follow" (asserts absence, reads as a verdict on their
+  thinking).
+- The "holding implicit / intended?" framing assumes the author has the step and
+  simply didn't write it. Use it.
+- Use first person for your own uncertainty: "I might be missing a step between
+  these two — is it stated somewhere?"
+- NAME THE GAP: name the absent link specifically. Never "this doesn't follow"
+  with nothing named. Ask, don't rule. No rewrites, no emoji.
+
+────────────────────────────────────────────────────────
+OUTPUT — for each finding, JSON:
+- paragraph_id
+- exact_text          (the conclusion + its grounds, verbatim)
+- annotation_type     "logic"
+- shape               e.g. "missing-warrant", "non-sequitur", "unsupported-leap"
+- justification       internal only — name the specific missing step between grounds and conclusion
+- suggested_note      author-facing — names the link, frames it as implicit, asks
+- severity            "minor" | "notable" | "significant"   (advisory only)
+- confidence          0.0–1.0
+
+Bias HARD toward an empty array — most paragraphs have no real logic gap.
+
+Input paragraphs:
+{{PARAGRAPHS_JSON}}
+
+Return valid JSON only:
+{ "findings": [] }`
+
+export interface AutoReviewParagraph {
+  id: string
+  text: string
+  from: number
+  to: number
+}
+
+export type AutoReviewPromptKind =
+  | 'claim'
+  | 'fact-check'
+  | 'source'
+  | 'thread'
+  | 'conflict'
+  | 'logic'
+  | 'copyedit'
+  | 'voice'
+export type AutoReviewFindingSeverity =
+  | 'info'
+  | 'warning'
+  | 'blocking'
+  | 'minor'
+  | 'notable'
+  | 'significant'
+export type EditorialAnnotationType =
+  | 'claim'
+  | 'fact-check'
+  | 'source'
+  | 'thread'
+  | 'conflict'
+  | 'logic'
+  | 'copyedit'
+  | 'voice'
+export type EditorialProcess =
+  | 'claims'
+  | 'fact-checks'
+  | 'claims-and-facts'
+  | 'source'
+  | 'source-and-thread'
+  | 'thread'
+  | 'conflict'
+  | 'logic'
+  | 'logic-and-conflict'
+  | 'full-editorial'
+  | 'copyedit'
+  | 'voice'
+export type EditorialGenreMode =
+  | 'infer'
+  | 'fiction'
+  | 'essay-opinion'
+  | 'scholarly'
+export type EditorialStrictness = 'low' | 'medium' | 'high'
+export type EditorialDensity = 'sparse' | 'normal'
+export type EditorialScope = 'local' | 'document'
+
+export interface EditorialFrameworkEntry {
+  type: EditorialAnnotationType
+  label: string
+  question: string
+  meaning: string
+  openStatus: 'open' | 'needs-support' | 'unverified' | 'suggested' | 'needs-review'
+  closedStatuses: string[]
+  color: 'amber' | 'red' | 'blue' | 'violet' | 'slate' | 'green' | 'pink'
+  resolver: string
+  disabledReason?: string
+}
+
+export const EDITORIAL_FRAMEWORK: Record<
+  EditorialAnnotationType,
+  EditorialFrameworkEntry
+> = {
+  claim: {
+    type: 'claim',
+    label: 'Claim',
+    question: 'Says who?',
+    meaning:
+      'An assertion the author advances that is not backed in the manuscript.',
+    openStatus: 'needs-support',
+    closedStatuses: ['resolved'],
+    color: 'amber',
+    resolver: 'author',
+  },
+  'fact-check': {
+    type: 'fact-check',
+    label: 'Fact check',
+    question: 'What source settles this?',
+    meaning:
+      'An external, source-settled statement whose truth does not depend on this manuscript.',
+    openStatus: 'unverified',
+    closedStatuses: ['verified', 'disputed'],
+    color: 'red',
+    resolver: 'verifier',
+  },
+  source: {
+    type: 'source',
+    label: 'Source',
+    question: 'Does the source say this?',
+    meaning:
+      'An attributed claim whose accuracy depends on whether the cited source supports it.',
+    openStatus: 'unverified',
+    closedStatuses: ['verified', 'disputed'],
+    color: 'blue',
+    resolver: 'source checker',
+  },
+  thread: {
+    type: 'thread',
+    label: 'Thread',
+    question: 'Where is the payoff?',
+    meaning:
+      'A promise to the reader, such as a forward reference, setup, or enumeration.',
+    openStatus: 'open',
+    closedStatuses: ['supported', 'rejected'],
+    color: 'violet',
+    resolver: 'author',
+  },
+  conflict: {
+    type: 'conflict',
+    label: 'Conflict',
+    question: 'Does this contradict elsewhere?',
+    meaning:
+      'A possible contradiction between two manuscript passages; requires retrieval before release.',
+    openStatus: 'needs-support',
+    closedStatuses: ['supported', 'rejected'],
+    color: 'slate',
+    resolver: 'author',
+    disabledReason: 'Requires internal retrieval before it can run.',
+  },
+  logic: {
+    type: 'logic',
+    label: 'Logic',
+    question: 'How does this follow?',
+    meaning:
+      'A sparse, opt-in check for clear reasoning gaps or missing warrants.',
+    openStatus: 'needs-support',
+    closedStatuses: ['supported', 'rejected'],
+    color: 'slate',
+    resolver: 'author',
+  },
+  copyedit: {
+    type: 'copyedit',
+    label: 'Copyedit',
+    question: 'What needs correcting?',
+    meaning:
+      'A correctness, usage, punctuation, or house-style issue that should be suggested but not auto-applied.',
+    openStatus: 'suggested',
+    closedStatuses: ['supported', 'rejected'],
+    color: 'green',
+    resolver: 'author',
+  },
+  voice: {
+    type: 'voice',
+    label: 'Voice',
+    question: 'Does this still sound like the author?',
+    meaning:
+      'A possible drift from the supplied author voice profile, especially smoothing toward generic prose.',
+    openStatus: 'needs-review',
+    closedStatuses: ['supported', 'rejected'],
+    color: 'pink',
+    resolver: 'author',
+  },
+}
+
+export function enabledEditorialTypesForProcess(
+  process: EditorialProcess = 'claims-and-facts',
+): EditorialAnnotationType[] {
+  if (process === 'claims') return ['claim']
+  if (process === 'fact-checks') return ['fact-check']
+  if (process === 'source') return ['source']
+  if (process === 'source-and-thread') return ['source', 'thread']
+  if (process === 'thread') return ['thread']
+  if (process === 'logic') return ['logic']
+  if (process === 'copyedit') return ['copyedit']
+  if (process === 'voice') return ['voice']
+  if (process === 'logic-and-conflict') return ['logic']
+  if (process === 'conflict') return []
+  if (process === 'full-editorial') {
+    return ['claim', 'fact-check', 'source', 'thread']
+  }
+  return ['claim', 'fact-check']
+}
+
+export interface AutoReviewFindingInput {
+  paragraph_id: string
+  exact_text: string
+  annotation_type:
+    | 'claim'
+    | 'fact_check'
+    | 'fact-check'
+    | 'source'
+    | 'thread'
+    | 'conflict'
+    | 'logic'
+    | 'copyedit'
+    | 'copy-edit'
+    | 'copy_edit'
+    | 'copyediting'
+    | 'copy-editing'
+    | 'voice'
+  shape?: string
+  subject?: string
+  justification?: string
+  suggested_note?: string
+  severity?: AutoReviewFindingSeverity
+  confidence?: number
+}
+
+export interface AutoReviewFindingResponse {
+  findings?: AutoReviewFindingInput[]
+  annotations?: AutoReviewFindingInput[]
+  items?: AutoReviewFindingInput[]
+  results?: AutoReviewFindingInput[]
+}
+
+export interface ValidatedAutoReviewFinding {
+  paragraphId: string
+  exactText: string
+  annotationType: CommentType
+  subject: string
+  note: string
+  severity: CommentSeverity
+  confidence: number
+  from: number
+  to: number
+}
+
+export interface AppliedAutoReviewFinding extends ValidatedAutoReviewFinding {
+  commentId: string
+}
+
+export interface AutoReviewFindingsProviderRequest {
+  paragraphs: AutoReviewParagraph[]
+  options: RunAutoReviewOptions
+}
+
+export type AutoReviewFindingsProvider = (
+  request: AutoReviewFindingsProviderRequest,
+) => Promise<AutoReviewFindingInput[]>
+
+export interface ApplyAutoReviewFindingsOptions {
+  author?: string
+  createdAt?: string
+  minConfidence?: number
+  idPrefix?: string
+}
+
+export interface RunAutoReviewOptions extends ApplyAutoReviewFindingsOptions {
+  process?: EditorialProcess
+  enabledTypes?: EditorialAnnotationType[]
+  genreMode?: EditorialGenreMode
+  strictness?: EditorialStrictness
+  density?: EditorialDensity
+  scope?: EditorialScope
+  maxFindings?: number
+  houseStyle?: string
+  voiceProfile?: string
+  signal?: AbortSignal
+  findingsProvider?: AutoReviewFindingsProvider
+  onProgress?: (result: RunAutoReviewResult) => void
+}
+
+export interface RunAutoReviewResult {
+  paragraphCount: number
+  findingCount: number
+  applied: AppliedAutoReviewFinding[]
+  skipped: number
+  unavailableReason?: string
+}
+
+export interface CopyAutoReviewPromptsResult {
+  copied: boolean
+  paragraphCount: number
+}
+
+declare module '@tiptap/core' {
+  interface Commands<ReturnType> {
+    autoReviewPrompts: {
+      applyAutoReviewFindings: (
+        paragraphs: AutoReviewParagraph[],
+        findings: AutoReviewFindingInput[],
+        options?: ApplyAutoReviewFindingsOptions,
+      ) => ReturnType
+    }
+  }
+}
+
+export const AutoReviewPrompts = Extension.create({
+  name: 'autoReviewPrompts',
+
+  addCommands() {
+    return {
+      applyAutoReviewFindings:
+        (paragraphs, findings, options) =>
+        ({ editor }) =>
+          applyAutoReviewFindings(editor, paragraphs, findings, options).applied
+            .length > 0,
+    }
+  },
+})
+
+export function collectAutoReviewParagraphs(
+  editor: Editor,
+): AutoReviewParagraph[] {
+  const paragraphs: AutoReviewParagraph[] = []
+  editor.state.doc.descendants((node, pos) => {
+    if (node.type.name !== 'paragraph') return true
+    if (isAutoReviewProtectedPosition(editor, pos + 1)) return false
+    const text = node.textContent.replace(/\s+/g, ' ').trim()
+    if (!text) return true
+    paragraphs.push({
+      id: `p-${paragraphs.length + 1}`,
+      text,
+      from: pos + 1,
+      to: pos + node.nodeSize - 1,
+    })
+    return false
+  })
+  return paragraphs
+}
+
+export function collectScopedAutoReviewParagraphs(
+  editor: Editor,
+  scope: EditorialScope = 'document',
+): AutoReviewParagraph[] {
+  const paragraphs = collectAutoReviewParagraphs(editor)
+  const { empty, from, to } = editor.state.selection
+  if (scope !== 'local' || empty) return paragraphs
+  return paragraphs.filter(
+    paragraph => paragraph.to >= from && paragraph.from <= to,
+  )
+}
+
+export function buildAutoReviewPrompt(
+  kind: AutoReviewPromptKind,
+  paragraphs: AutoReviewParagraph[],
+): string {
+  const payload = paragraphs.map(({ id, text }) => ({ id, text }))
+  const template = autoReviewPromptTemplate(kind)
+  return template.replace(
+    '{{PARAGRAPHS_JSON}}',
+    JSON.stringify(payload, null, 2),
+  )
+}
+
+export function buildAutoReviewPromptBundle(
+  paragraphs: AutoReviewParagraph[],
+): string {
+  return [
+    '# Claim detection prompt',
+    buildAutoReviewPrompt('claim', paragraphs),
+    '',
+    '# Fact-check detection prompt',
+    buildAutoReviewPrompt('fact-check', paragraphs),
+    '',
+    '# Source detection prompt',
+    buildAutoReviewPrompt('source', paragraphs),
+    '',
+    '# Thread detection prompt',
+    buildAutoReviewPrompt('thread', paragraphs),
+    '',
+    '# Logic detection prompt',
+    buildAutoReviewPrompt('logic', paragraphs),
+    '',
+    '# Copyedit prompt',
+    buildAutoReviewPrompt('copyedit', paragraphs),
+    '',
+    '# Voice prompt',
+    buildAutoReviewPrompt('voice', paragraphs),
+  ].join('\n\n')
+}
+
+export async function copyAutoReviewPromptsToClipboard(
+  editor: Editor,
+): Promise<CopyAutoReviewPromptsResult> {
+  const paragraphs = collectAutoReviewParagraphs(editor)
+  if (!paragraphs.length) return { copied: false, paragraphCount: 0 }
+  await navigator.clipboard.writeText(buildAutoReviewPromptBundle(paragraphs))
+  return { copied: true, paragraphCount: paragraphs.length }
+}
+
+export function parseAutoReviewFindingResponse(
+  value: string,
+): AutoReviewFindingInput[] {
+  const parsed = JSON.parse(value) as unknown
+  return normalizeAutoReviewFindingResponse(parsed)
+}
+
+export function validateAutoReviewFindings(
+  paragraphs: AutoReviewParagraph[],
+  findings: AutoReviewFindingInput[],
+  options: Pick<ApplyAutoReviewFindingsOptions, 'minConfidence'> = {},
+): ValidatedAutoReviewFinding[] {
+  const minConfidence = options.minConfidence ?? 0.55
+  const paragraphsById = new Map(
+    paragraphs.map(paragraph => [paragraph.id, paragraph]),
+  )
+  const occupied = new Set<string>()
+  const validated: ValidatedAutoReviewFinding[] = []
+
+  for (const rawFinding of findings) {
+    const finding = normalizeAutoReviewFinding(rawFinding)
+    if (!finding) continue
+    const paragraph = paragraphsById.get(finding.paragraph_id)
+    if (!paragraph) continue
+    const exactText = normalizeFindingText(finding.exact_text)
+    if (!exactText) continue
+    const confidence =
+      typeof finding.confidence === 'number' &&
+      Number.isFinite(finding.confidence)
+        ? finding.confidence
+        : 1
+    if (confidence < minConfidence) continue
+    const match = findAutoReviewSpan(paragraph.text, exactText)
+    if (!match) continue
+
+    const annotationType = normalizeAutoReviewAnnotationType(
+      finding.annotation_type,
+    )
+    if (!annotationType) continue
+    const key = `${paragraph.id}:${match.index}:${exactText}:${annotationType}`
+    if (occupied.has(key)) continue
+    occupied.add(key)
+
+    const from = paragraph.from + match.index
+    validated.push({
+      paragraphId: paragraph.id,
+      exactText: match.text,
+      annotationType,
+      subject:
+        normalizeFindingText(finding.subject) ||
+        normalizeFindingText(finding.shape) ||
+        match.text,
+      note: buildFindingNote(finding),
+      severity: normalizeFindingSeverity(finding.severity),
+      confidence,
+      from,
+      to: from + match.text.length,
+    })
+  }
+
+  return preferFactChecksForDuplicateSpans(validated)
+}
+
+export function applyAutoReviewFindings(
+  editor: Editor,
+  paragraphs: AutoReviewParagraph[],
+  findings: AutoReviewFindingInput[],
+  options: ApplyAutoReviewFindingsOptions = {},
+): { applied: AppliedAutoReviewFinding[]; skipped: number } {
+  const validated = validateAutoReviewFindings(paragraphs, findings, options)
+  const now = options.createdAt ?? new Date().toISOString()
+  const applied: AppliedAutoReviewFinding[] = []
+
+  validated.forEach((finding, index) => {
+    if (rangeHasAutoReviewMark(editor, finding)) return
+    const id = [
+      options.idPrefix ?? 'auto-review',
+      finding.annotationType,
+      now.replace(/\W+/g, '-'),
+      index + 1,
+    ].join('-')
+    const appliedMark = applyCommentMarkToRange(
+      editor,
+      finding.from,
+      finding.to,
+      {
+        commentId: id,
+        commentText: finding.note,
+        commentType: finding.annotationType,
+        subjectText: finding.exactText,
+        author: options.author ?? 'Auto review',
+        createdAt: now,
+        reviewStatus: defaultAutoReviewStatus(finding.annotationType),
+        severity: finding.severity,
+      },
+      { scrollIntoView: false, focusEditor: false },
+    )
+    if (appliedMark) applied.push({ ...finding, commentId: id })
+  })
+
+  return { applied, skipped: findings.length - applied.length }
+}
+
+export async function runAutoReview(
+  editor: Editor,
+  options: RunAutoReviewOptions = {},
+): Promise<RunAutoReviewResult> {
+  const paragraphs = collectScopedAutoReviewParagraphs(editor, options.scope)
+  options.onProgress?.({
+    paragraphCount: paragraphs.length,
+    findingCount: 0,
+    applied: [],
+    skipped: 0,
+  })
+  if (!options.findingsProvider) {
+    return {
+      paragraphCount: paragraphs.length,
+      findingCount: 0,
+      applied: [],
+      skipped: 0,
+      unavailableReason: 'Editorial review provider is not configured.',
+    }
+  }
+  const findings = await options.findingsProvider({ paragraphs, options })
+  const result = applyAutoReviewFindings(editor, paragraphs, findings, {
+    ...options,
+    author: options.author ?? 'Auto review',
+    idPrefix: options.idPrefix ?? 'auto-review',
+  })
+  const runResult = {
+    paragraphCount: paragraphs.length,
+    findingCount: findings.length,
+    applied: result.applied,
+    skipped: result.skipped,
+  }
+  options.onProgress?.(runResult)
+  return runResult
+}
+
+function normalizeAutoReviewAnnotationType(
+  value: AutoReviewFindingInput['annotation_type'] | string | undefined,
+): EditorialAnnotationType | null {
+  const normalized = normalizeFindingText(value).toLowerCase()
+  if (normalized === 'claim') return 'claim'
+  if (
+    normalized === 'fact_check' ||
+    normalized === 'fact-check' ||
+    normalized === 'fact check' ||
+    normalized === 'factcheck'
+  ) {
+    return 'fact-check'
+  }
+  if (
+    normalized === 'source' ||
+    normalized === 'thread' ||
+    normalized === 'conflict' ||
+    normalized === 'logic' ||
+    normalized === 'voice'
+  ) {
+    return normalized
+  }
+  if (
+    normalized === 'copyedit' ||
+    normalized === 'copy-edit' ||
+    normalized === 'copy edit' ||
+    normalized === 'copy_edit' ||
+    normalized === 'copyediting' ||
+    normalized === 'copy-editing'
+  ) {
+    return 'copyedit'
+  }
+  return null
+}
+
+function autoReviewPromptTemplate(kind: AutoReviewPromptKind): string {
+  switch (kind) {
+    case 'claim':
+      return AUTO_CLAIM_REVIEW_PROMPT
+    case 'fact-check':
+      return AUTO_FACT_CHECK_REVIEW_PROMPT
+    case 'source':
+      return AUTO_SOURCE_REVIEW_PROMPT
+    case 'thread':
+      return AUTO_THREAD_REVIEW_PROMPT
+    case 'conflict':
+      return AUTO_CONFLICT_REVIEW_PROMPT
+    case 'logic':
+      return AUTO_LOGIC_REVIEW_PROMPT
+    case 'copyedit':
+      return AUTO_COPYEDIT_REVIEW_PROMPT
+    case 'voice':
+      return AUTO_VOICE_REVIEW_PROMPT
+  }
+}
+
+function defaultAutoReviewStatus(
+  annotationType: CommentType,
+): CommentReviewStatus {
+  if (annotationType === 'fact-check' || annotationType === 'source') {
+    return 'unverified'
+  }
+  if (annotationType === 'thread') return 'open'
+  if (annotationType === 'copyedit') return 'suggested'
+  if (annotationType === 'voice') return 'needs-review'
+  return 'needs-support'
+}
+
+function normalizeFindingText(value: string | undefined): string {
+  return typeof value === 'string' ? value.replace(/\s+/g, ' ').trim() : ''
+}
+
+function normalizeAutoReviewFindingResponse(
+  value: unknown,
+): AutoReviewFindingInput[] {
+  const candidates = Array.isArray(value)
+    ? value
+    : value && typeof value === 'object'
+    ? (['findings', 'annotations', 'items', 'results'] as const).reduce<
+        unknown[]
+      >((result, key) => {
+        if (result.length) return result
+        const candidate = (value as AutoReviewFindingResponse)[key]
+        return Array.isArray(candidate) ? candidate : result
+      }, [])
+    : []
+
+  return candidates
+    .map(candidate => normalizeAutoReviewFinding(candidate))
+    .filter((finding): finding is AutoReviewFindingInput => finding !== null)
+}
+
+function normalizeAutoReviewFinding(
+  value: unknown,
+): AutoReviewFindingInput | null {
+  if (!value || typeof value !== 'object') return null
+  const record = value as Record<string, unknown>
+  const paragraphId = firstString(
+    record.paragraph_id,
+    record.paragraphId,
+    record.paragraph,
+    record.id,
+  )
+  const exactText = firstString(
+    record.exact_text,
+    record.exactText,
+    record.span,
+    record.text,
+    record.quote,
+  )
+  const annotationType = firstString(
+    record.annotation_type,
+    record.annotationType,
+    record.type,
+    record.kind,
+  )
+  if (!paragraphId || !exactText || !annotationType) return null
+  const normalizedAnnotationType =
+    normalizeAutoReviewAnnotationType(annotationType)
+  if (!normalizedAnnotationType) return null
+  const confidence =
+    typeof record.confidence === 'number' && Number.isFinite(record.confidence)
+      ? record.confidence
+      : typeof record.score === 'number' && Number.isFinite(record.score)
+      ? record.score
+      : undefined
+  const severity = firstString(record.severity) as
+    | AutoReviewFindingSeverity
+    | undefined
+
+  return {
+    paragraph_id: paragraphId,
+    exact_text: exactText,
+    annotation_type:
+      normalizedAnnotationType === 'fact-check'
+        ? 'fact_check'
+        : normalizedAnnotationType,
+    shape: firstString(record.shape, record.category),
+    subject: firstString(record.subject),
+    justification: firstString(record.justification, record.reason),
+    suggested_note: firstString(
+      record.suggested_note,
+      record.suggestedNote,
+      record.note,
+      record.comment,
+    ),
+    severity,
+    confidence,
+  }
+}
+
+function firstString(...values: unknown[]): string | undefined {
+  for (const value of values) {
+    if (typeof value === 'string' && value.trim()) return value
+  }
+  return undefined
+}
+
+function findAutoReviewSpan(
+  paragraphText: string,
+  exactText: string,
+): { index: number; text: string } | null {
+  const directIndex = paragraphText.indexOf(exactText)
+  if (directIndex >= 0) {
+    return { index: directIndex, text: exactText }
+  }
+
+  const foldedParagraph = foldAutoReviewTextWithMap(paragraphText)
+  const foldedExact = foldAutoReviewText(exactText)
+  if (!foldedExact) return null
+  const foldedIndex = foldedParagraph.text.indexOf(foldedExact)
+  if (foldedIndex < 0) return null
+  const start = foldedParagraph.map[foldedIndex]
+  const lastFoldedIndex = foldedIndex + foldedExact.length - 1
+  const end =
+    (foldedParagraph.map[lastFoldedIndex] ?? start) +
+    (paragraphText[foldedParagraph.map[lastFoldedIndex] ?? start]?.length ?? 1)
+  return { index: start, text: paragraphText.slice(start, end) }
+}
+
+function foldAutoReviewText(value: string): string {
+  return foldAutoReviewTextWithMap(value).text
+}
+
+function foldAutoReviewTextWithMap(value: string): {
+  text: string
+  map: number[]
+} {
+  let text = ''
+  const map: number[] = []
+  let previousWasSpace = true
+  for (let index = 0; index < value.length; index += 1) {
+    const folded = foldAutoReviewChar(value[index] ?? '')
+    if (!folded) continue
+    if (/\s/.test(folded)) {
+      if (previousWasSpace) continue
+      text += ' '
+      map.push(index)
+      previousWasSpace = true
+      continue
+    }
+    text += folded
+    map.push(index)
+    previousWasSpace = false
+  }
+  return {
+    text: text.trimEnd(),
+    map: map.slice(0, text.trimEnd().length),
+  }
+}
+
+function foldAutoReviewChar(char: string): string {
+  if (char === '“' || char === '”') return '"'
+  if (char === '‘' || char === '’') return "'"
+  if (char === '–' || char === '—') return '-'
+  if (char === '…') return '.'
+  return char.toLowerCase()
+}
+
+function normalizeFindingSeverity(
+  value: AutoReviewFindingSeverity | undefined,
+): CommentSeverity {
+  if (value === 'blocking') return 'blocking'
+  if (value === 'warning' || value === 'notable' || value === 'significant') {
+    return 'advisory'
+  }
+  return 'note'
+}
+
+function buildFindingNote(finding: AutoReviewFindingInput): string {
+  const suggested = normalizeFindingText(finding.suggested_note)
+  const justification = normalizeFindingText(finding.justification)
+  return suggested || justification || 'Review this passage.'
+}
+
+function preferFactChecksForDuplicateSpans(
+  findings: ValidatedAutoReviewFinding[],
+): ValidatedAutoReviewFinding[] {
+  const bySpan = new Map<string, ValidatedAutoReviewFinding>()
+  for (const finding of findings) {
+    const key = `${finding.from}:${finding.to}:${finding.exactText}`
+    const existing = bySpan.get(key)
+    if (
+      !existing ||
+      (existing.annotationType === 'claim' &&
+        finding.annotationType === 'fact-check')
+    ) {
+      bySpan.set(key, finding)
+    }
+  }
+  return Array.from(bySpan.values())
+}
+
+function rangeHasAutoReviewMark(
+  editor: Editor,
+  finding: ValidatedAutoReviewFinding,
+): boolean {
+  let found = false
+  editor.state.doc.nodesBetween(finding.from, finding.to, node => {
+    if (found || !node.isText) return !found
+    found = node.marks.some(
+      mark =>
+        mark.type.name === 'commentMark' &&
+        mark.attrs.commentType === finding.annotationType &&
+        mark.attrs.subjectText === finding.exactText,
+    )
+    return !found
+  })
+  return found
+}
+
+function isAutoReviewProtectedPosition(editor: Editor, pos: number): boolean {
+  try {
+    const dom = editor.view.domAtPos(pos).node
+    const element = dom instanceof HTMLElement ? dom : dom.parentElement
+    return Boolean(
+      element?.closest(
+        [
+          '[contenteditable="false"]',
+          'cite.ps-citation',
+          '[data-pm-reference-entry="true"]',
+          '[data-pm-generated-references="true"]',
+          '[data-pm-references-empty="true"]',
+        ].join(','),
+      ),
+    )
+  } catch {
+    return false
+  }
+}