@maestroagora/agora 1.8.0 → 1.10.0

package/skills/agora/references/agora-case-study-runtime.md

@@ -0,0 +1,31 @@
+# Agora case-study runtime
+
+Use this compact file for ordinary customer-success, creative-portfolio, and technical-implementation cases. Load the deep case-study reference only for explicit source review, attribution or permission review, confidentiality review, technical evaluation, audit work, or maintainer analysis.
+
+## Choose the case job
+
+- `CUSTOMER_SUCCESS`: the customer's situation, what changed, and the supplied result.
+- `CREATIVE_PORTFOLIO`: the brief, constraints, decisions, role, work, and supplied result.
+- `TECHNICAL_IMPLEMENTATION`: the system constraint, chosen approach, implementation, observed behavior, and tradeoffs.
+
+Keep real, fictional, mock, and concept status as the user supplies it. Do not add a status label unless requested.
+
+Academic and clinical case reports are outside this runtime.
+
+## Preserve what happened
+
+Use only supplied history, roles, facts, quotations, measurements, and outcomes unless invention is authorized. Do not turn chronology into causation. Keep measured results, reported results, observed changes, supported inferences, targets, pending measurements, and unknowns distinct when the brief distinguishes them.
+
+Do not invent customer motives, internal reactions, implementation steps, permissions, confidentiality terms, quotes, or typicality.
+
+## Shape the case
+
+Start with the most useful situation or result for the intended reader. Explain the constraint, the relevant decision, the work, and what changed. Give each section a distinct job. Keep failed attempts or tradeoffs when they explain the decision.
+
+State each limitation once, beside the fact it limits. Do not repeat the same causal or outcome limit in a closing recap.
+
+For a public case, translate internal review language into customer language. For a technical audience, keep exact system terms and behavior. For sales work, do not turn the case into a chronology or an academic report.
+
+## Return the case
+
+Return the requested case only. Keep source review, permission checks, and internal classifications private unless the user asks for them.

package/skills/agora/references/agora-conversion-runtime.md

@@ -0,0 +1,49 @@
+# Agora conversion runtime
+
+Use this compact overlay for landing pages, product pages, pricing pages, paywalls, checkout, forms, onboarding, upgrade paths, and conversion experiments. Use the deep conversion research reference only when the user asks for research-backed guidance, source review, experiment interpretation, an audit, or maintainer analysis.
+
+## Start from the decision
+
+Identify the reader's current state, the action the surface asks them to take, what happens after that action, and the business outcome the task actually names.
+
+Do not confuse a click with activation, retention, revenue, or another later outcome. Do not claim that a pattern always converts better.
+
+## Keep the fact set closed
+
+Use only supplied routes, prices, terms, commitments, permissions, timing, data use, product behavior, and results. Do not infer self-service access, a sales handoff, a trial, a demo, a download, a confirmation screen, or an implementation step that the brief does not provide.
+
+Keep parallel options separate when they differ in access, effort, exclusivity, price, or commitment. Unknown transitions remain unknown.
+
+Classify each requested component as implementation direction, visible copy, or both. Keep editorial directions and worksheet labels outside ready-to-use copy.
+
+## Make the action clear
+
+State the benefit in reader language, then give the minimum supplied detail needed to believe or choose it. Put the strongest relevant supporting fact near the doubt it answers.
+
+The main action must name its object or destination. Do not use a prerequisite as the main action when the desired event happens later. Keep optional post-action steps secondary.
+
+For a multi-step flow, trace the current state, control, immediate effect, next visible state, and any conditional later state. Keep unsupplied states unknown. Optional consent stays separate from the primary action.
+
+## Match effort and commitment
+
+Make field effort, required information, eligibility, timing, price, renewal, cancellation, and reversibility visible where they affect the choice. Do not hide a material commitment in distant copy.
+
+For pricing, make each available path understandable from the supplied facts. Do not invent feature parity, savings, plan eligibility, negotiation, or billing terms.
+
+Preserve exact prices, billing periods, renewal terms, cancellation rights, trial terms, access timing, collection timing, capability names, regions, role names, availability windows, document status, access conditions, and exclusions. Arithmetic can establish a total, not an unsupplied sequence or collection date.
+
+Use quotation marks only for exact wording supplied as a quotation. A summary of what someone said supplies meaning, not exact speech.
+
+For onboarding, distinguish account creation, setup, activation, and later use. Name the event the task wants to improve.
+
+## Handle experiments
+
+When the user asks for an experiment plan, define the changed element, the eligible population, the primary outcome, guardrails, duration or stopping rule when supplied, and the decision the result will inform. Keep the plan proportional to the request.
+
+When the user asks for interpretation, preserve conflicts, null results, uncertainty, and differences between intermediate and business outcomes. Do not turn one test into a universal rule.
+
+After factual and route requirements pass, preserve the strongest supported reader job as the argument. Do not flatten the surface into an internal evaluation checklist.
+
+## Return the surface
+
+Return the requested copy or implementation decision. Do not append an internal review, rationale, or checklist unless requested.

package/skills/agora/references/agora-craft.md

@@ -527,33 +527,25 @@ The strongest surviving machine-writing tell is cadence rather than vocabulary.
 
 ### The rhythm targets
 
-Every value in the table below is a **governance default**: a control setting chosen so the system has something checkable to enforce instead of the instruction to sound less uniform. The research grades all of them as engineering heuristics with no controlled literature establishing universal values for good prose. None of them is a finding, none may be cited as one, and each is a review trigger rather than an error.
+Numeric sentence-length and paragraph-shape measurements belong in `voice check` and optional diagnostics. They do not set drafting targets.
 
-| Control | Default | Status | Reading |
-|---|---|---|---|
-| Sentence-length spread | For expository prose of at least 20 sentences, a standard deviation of 8 to 12 words with a coefficient of variation of 0.40 to 0.70 | Governance default | Below roughly 6 words of deviation at an 18 to 22 word mean, review for metronomic pacing. Above roughly 15, review for uncontrolled extremes. |
-| Length tails | In a passage of 10 or more sentences, include at least one sentence of 8 words or fewer and one of 25 or more, but only where both are natural | Governance default | A forcing mechanism against middle-length clustering. Drop it wherever it produces a stunt sentence. |
-| Consecutive similar lengths | Flag 3 consecutive sentences when every pair differs by 3 words or fewer | Governance default | Review for accidental monotony. Deliberate parallelism overrides the flag. |
-| Paragraph variation | Over 8 or more paragraphs, aim for a coefficient of variation of at least 0.45 in words | Governance default | Prevents identical blocks without demanding arbitrary one-sentence paragraphs. |
-| Opening structure | At most 2 consecutive sentences opening with the same class, such as subject-first declarative, initial subordinate clause, or imperative | Governance default | Catches repeated `Subject plus verb` starts that length statistics miss. Intentional parallelism overrides it. |
-| Opening dominance | In a rolling 10-sentence window, flag any opening class occupying more than 60 percent | Governance default | Review trigger only. |
-| Clause-count variation | No more than 4 consecutive sentences with the same finite-clause count, unless the passage is deliberately parallel | Governance default | Catches syntactic monotony that survives length variation. |
+No instruction requires a long sentence, a short sentence after a long one, alternating lengths, a target distribution, a coefficient of variation, a tail value, or a repeated-opening quota. Sentence and paragraph shape follow the idea, audience, genre, and active voice.
 
-Where an authorized author profile exists, its measured corpus ranges replace every governance default above, because a measurement of that writer beats a default chosen for everyone. A writer whose corpus naturally runs wider than the spread row must not be normalized down into it, and a writer whose professional register is short briefing paragraphs must not be forced into long blocks.
+Review an ordinary sentence over 28 words. Keep it when splitting would damage a necessary relationship or exact meaning. Review repeated openings and identical paragraph shapes as possible patterns, not automatic failures. Buttons, headings, tables, lists, captions, code, identifiers, URLs, immutable quotations, legal text, and exact technical text keep their native form.
 
-**Boundary on the whole table:** these are controls for continuous prose. They do not apply to a button, a heading set, a table, a list, a caption, or a form label, and they are not evidence about how any reader responds.
+An authorized measured profile may describe the writer's habits. Use those measurements for optional comparison only. Do not generate toward a number or manufacture irregularity to resemble the corpus.
 
 ### The conflict this document does not resolve
 
 Two positions on cadence are in direct conflict, and neither side is strong enough to win.
 
-**The research position** is deliberate variance, expressed in the spread targets above.
+**The research position** is that measured variance can prompt editorial review.
 
 **The practitioner position** is uniform brevity. Experienced conversion copywriters advise short, choppy sentences, paragraphs of no more than two or three lines, and one-sentence paragraphs as the ideal, on scanned commercial surfaces.
 
 The most likely resolution is register: a landing page read by a scanning cold visitor is a different problem from expository prose read continuously, and the practitioners are talking about the first. That is a hypothesis. It has not been tested, neither position is graded above the level of an engineering heuristic, and this document adopts neither as universal.
 
-**What to do meanwhile:** apply the variance targets to continuous prose, apply the brevity preference to scanned commercial surfaces, and record which you applied if the choice is consequential. Do not report either as a finding, and do not resolve the conflict by quietly picking one.
+**What to do meanwhile:** let the idea and surface determine sentence shape. Use measured variance only as an optional diagnostic. Do not report either position as a finding.
 
 ## Open conflicts in this reference
 
@@ -562,4 +554,4 @@ Recorded so that neither side is lost. Do not close either by writing a rule.
 | Conflict | Position A | Position B | Status |
 |---|---|---|---|
 | Question-form subheadings | Practitioners reject them outright: give the answer instead of asking. | A direct observation in this project found question headings reading better than abstract noun-stack statement headings on the same page. | Open. The untested hypothesis is that questions beat noun stacks and lose to concrete answers. Neither side is graded above an assertion. |
-| Sentence cadence | Deliberate variance, per the targets above. | Uniform brevity on scanned commercial surfaces. | Open, probably register-dependent. Neither position is better than an engineering heuristic. |
+| Sentence cadence | Measured variance can prompt review. | Uniform brevity can fit scanned commercial surfaces. | Open, probably register-dependent. Neither position sets a generation quota. |

package/skills/agora/references/agora-marketing-runtime.md

@@ -0,0 +1,85 @@
+# Agora marketing runtime
+
+Use this compact file for ordinary `POSITION`, `SELL`, `INFORM`, and `TRANSACT` work. Use the deep marketing research reference only when the user asks for research-backed guidance, source review, an audit, or maintainer analysis.
+
+## Decide before planning
+
+Resolve these items in order:
+
+1. Required facts and exact wording.
+2. Deliverable, audience, genre, and length.
+3. Writing register.
+4. Persistent voice profile, task voice sketch, or plain default.
+5. Primary job and publication surface.
+6. The smallest useful argument.
+
+The default register is `PLAIN`. Choose `TECHNICAL`, `SCIENTIFIC`, `LEGAL_OR_COMPLIANCE`, or `AUDIT_OR_DILIGENCE` only when the requested job, audience, genre, or immutable text needs it. Topic words such as AI, software, data, security, engineering, and infrastructure do not choose the register.
+
+## Choose one primary job
+
+- `POSITION`: company profiles, About copy, category descriptions, and objective summaries.
+- `SELL`: marketing, sales, product pages, outreach, upgrades, and paywalls.
+- `INVEST`: fundraising, diligence, and capital decisions.
+- `INFORM`: editorial, educational, scientific, or technical explanation.
+- `TRANSACT`: buttons, forms, confirmations, alerts, and utility text.
+
+Choose the publication surface separately. Apply search and publication formatting only to indexable public work.
+
+## Preserve the brief
+
+Treat supplied product, offer, customer, result, price, term, route, permission, process, timing, legal, and outcome facts as the complete fact set unless the user authorizes invention.
+
+Do not invent names, figures, quotations, results, credentials, permissions, URLs, destinations, product behavior, or intermediate steps. Keep every material condition, limit, attribution, certainty level, and exact required term.
+
+Voice shapes sentence construction, paragraph shape, vocabulary, directness, openings, endings, rhythm, and where qualifications sit. Voice never changes facts or required wording.
+
+## Build the argument
+
+Start from the audience's live situation and next decision. Use only the moves the deliverable needs:
+
+```text
+situation -> stake -> useful difference -> how it works -> reason to believe -> next step
+```
+
+This is private planning, not a visible template. Very short copy may need only the live constraint, the strongest supplied difference, and the next action. Add detail only when it resolves a real doubt or enables action.
+
+For a very short company profile, a trigger or condition can lead when it makes the subject easier to understand. Retain the subject's primary supplied operation. Reordering may not reduce the company to an error state or downstream action.
+
+For very short sales copy, keep the exact constraint, conflict, threshold, or blocked action from the brief. Do not weaken a specific problem into generic complexity or challenges.
+
+Rank supplied facts by relevance to the reader's decision, differentiation, specificity, compression value, and omission risk. Preserve named limits, counts, coverage, entities, qualifications, and necessary lists. An inclusion statement does not communicate an excluded remainder when the exclusion is material.
+
+For customer-facing writing, name what the product or person does and what the reader can observe. Drop internal method names when the reader gains nothing from learning them.
+
+Preserve delivery ownership. Keep what the provider does, what the buyer supplies, the amount and timing of buyer work, dependencies, approvals, and coordination at the supplied level. Do not invent or magnify preparation, training, review cycles, handoffs, response times, or frequency.
+
+Do not add a plausible use case, reporting process, planning responsibility, reader behavior, comparison criterion, or benefit merely to make a section feel complete. Use only reader interpretations that follow directly from the supplied facts.
+
+When rewriting supplied copy, compare the candidate with the source for promise strength, certainty, buyer effort, provider responsibility, specificity, and next action. Keep the source when the candidate introduces a material regression or no material improvement.
+
+## Fit the channel
+
+- Heroes and ads: one recognizable stake, one meaningful difference, and the correct next action.
+- Product and comparison pages: explain enough for the reader to judge fit, terms, effort, and risk. Use prose unless the user asks for a specification table, field list, or checklist.
+- Company profiles: make the company easy to place and distinct without investor or audit language.
+- Professional email: put the request and needed context where they are easy to find.
+- Cold sales email: include a subject, greeting, brief body, and next step. When the copy is a reusable template and no recipient name is supplied, `[First name]` is an acceptable fill-in label.
+- Editorial work: give the reader useful reasoning before any commercial pressure.
+- Spoken work: use audible transitions, manageable clauses, and one clear ending.
+- Interface copy: name the state, action, object, or destination.
+
+For a button, prefer the immediate effect the user triggers. If selecting the button sends invitations, use `Send invitations` rather than a generic object label.
+
+If the brief supplies a required final shot, cancel consequence, negative capability, or exact product category, carry it into the requested component. Compression does not authorize omission.
+
+## Write calls to action
+
+Use a clear verb plus the concrete object, destination, or result. Match the commitment to what happens next. Do not invent a URL or destination.
+
+When no destination URL is supplied, return the action label as plain copy. Do not invent `#`, a dummy address, a route, or unresolved link markup.
+
+Keep one label for one materially identical action. If the brief names a report, form, preview, dashboard, demo, plan, or download, name it in the control or adjacent text.
+
+## Return the copy
+
+Return one recommended deliverable by default. Keep planning, fact checks, review notes, worksheet labels, and internal route names outside the ready-to-use copy unless the user requests them.

package/skills/agora/references/agora-marketing.md

@@ -334,6 +334,29 @@ A sentence fails when it:
 
 The last item is the hardest to catch from inside the draft, because impressive and clear feel similar to an author who already knows the answer. Use the literal-meaning test in `Required comprehension tests` on any sentence that felt satisfying to write.
 
+### The literal clarity rewrite
+
+Draft twice and return once. Build the factually complete argument first. Then rewrite the entire draft for literal clarity before style, compression, voice, GEO/AEO, or publication work. Compare the rewrite with the factual draft so every supplied fact, qualifier, relationship, and requested claim survives. Return only the rewrite.
+
+This is a passage rewrite, not a word-substitution pass. Run it on every sentence that carries a mechanism, consequence, qualification, or decision:
+
+1. Name the concrete actor, product, component, person, or source.
+2. Use a finite action the reader owns when it preserves the meaning.
+3. Name the concrete object affected.
+4. State the observable result, condition, or change when the claim depends on one.
+
+**Generic-referent gate.** Words such as `interface`, `surface`, `system`, `asset`, `signal`, `representation`, `direction`, `property`, `origin`, and `continuity` are review triggers, not banned words. Keep one when its concrete referent is unmistakable and the word adds meaning. When the reader could reasonably ask which interface, surface, system, asset, signal, representation, direction, property, origin, or continuity the sentence means, name the concrete thing in that sentence.
+
+**Observable-result gate.** Ask what a person could see happen. `The answer listed the product` exposes an event. `The footprint entered an answer surface` hides it inside two categories. For technical or empirical prose, distinguish what happened, how it was observed, and what it may imply. Do not replace the observed event with the method used to classify it.
+
+**Metaphor-recovery gate.** A metaphor may add emphasis after the mechanism is clear. It may not carry the only statement of the mechanism, test, or consequence. If the reader has to translate `carry the trust burden`, `flatten into one voice`, or `the asset breaks` before understanding the point, state the literal check, presentation effect, or failure instead. Keep a metaphor only when removing it leaves the sentence's factual relation intact and obvious.
+
+**Qualification-distribution gate.** Preserve material source, sample, date, product, market, method, condition, and uncertainty at passage level. Give the observed result its own sentence when possible, then place its scope and limit in adjacent sentences. Do not make one sentence independently quotable by forcing every qualifier into it.
+
+**Noun-stack gate.** When several unfamiliar abstract nouns appear together, recover each relationship the reader needs as an actor and action. Do not apply a fixed noun limit. Keep an established concept when it creates useful cohesion or precision; rewrite it when it hides who did what or what changed.
+
+**Revision-integrity gate.** Compare the rewrite with both the source and the failed wording. Reject a revision when it replaces one vague noun with another, converts one hidden action into a different abstraction, adds parentheses around the same unclear phrase, or drops a qualifier to create fluency. The revised passage must make the concrete actor, action, object, and observable result easier to recover without weakening the proposition.
+
 ### The specialized-term gate
 
 Do not expose internal product, operational, analytical, or methodological terminology merely because it is accurate.
@@ -463,14 +486,13 @@ Where this warning fails: internal boredom and a genuine template tell look iden
 
 When copy fails these tests:
 
-1. Preserve the underlying fact.
-2. Identify the concrete actor, action, object, and result.
+1. Preserve the underlying fact and every material qualifier.
+2. Rewrite the full sentence or short passage through `The literal clarity rewrite`.
 3. Remove internal process language unless the reader needs it.
-4. Split overloaded sentences.
-5. Replace abstractions with observable actions or conditions.
-6. Restore necessary context that compression removed.
-7. Rewrite the call to action to name its actual destination.
-8. Test the revision again.
+4. Split overloaded sentences and distribute their qualifications.
+5. Compare the revision with both the factual draft and the failed wording.
+6. Rewrite the call to action to name its actual destination.
+7. Test the revision again.
 
 Do not repair unclear writing by adding more jargon, explanatory parentheses, longer noun phrases, or vague supporting sentences. Those raise word count and decoding effort at the same time.
 
@@ -482,6 +504,11 @@ Run all of these before accepting customer-facing writing.
 |---|---|
 | First-read | Can the intended reader restate the sentence after one reading? |
 | Actor-action-object | Is it clear who or what acts, what the action is, and what it affects? |
+| Generic referent | Does every generic system or category noun identify the concrete thing it means when ambiguity is possible? |
+| Observable result | Can the reader tell what a person could see happen, separately from how the event was classified or interpreted? |
+| Metaphor recovery | If the metaphor is removed, does the sentence still state the literal mechanism, test, or consequence? |
+| Qualification distribution | Does the short passage preserve every material qualifier without forcing them into one sentence? |
+| Revision integrity | Does the rewrite remove the original decoding work instead of renaming it or hiding it elsewhere? |
 | Delivery-model ownership | Does the provider or product still perform the work the offer sells, without invented or magnified buyer burden? |
 | Rewrite regression | Does every source strength outside the requested transformation survive or materially improve? |
 | Abstraction | Can any abstract noun be replaced with a concrete action, object, condition, or result? |
@@ -792,73 +819,9 @@ Treat an existence-only route, screen, page, preview, or report as action availa
 
 ## Human voice and AI-writing-tell gate
 
-Apply this gate after the argument and proof pass. Its purpose is specific, accurate, author-owned prose. It does not prove human authorship or guarantee detector outcomes.
-
-### Global output bans
-
-Hard invariant: emit zero U+2014 characters in the entire response. This applies to copy, headings, lists, critique, explanations, notes, metadata, quotations, and text copied from user or source material. Do not repeat U+2014 from an input. Replace it with a period, comma, colon, semicolon, parentheses, or plain hyphen as grammar requires.
-
-If an exact quotation contains U+2014, paraphrase it or state that it cannot be reproduced verbatim under the active constraint. Never alter a quotation and still present it as exact. After all drafting and editing, scan the complete response character by character for U+2014, replace every occurrence, and scan again. Return only when the count is zero.
-
-Unless immutable quoted, legal, technical, or user-required text must be preserved, also generate:
-
-- no curly or smart quotation marks;
-- no prompt acknowledgements or task meta-commentary;
-- no fabricated citations, quotations, anecdotes, memories, motives, credentials, or human texture;
-- no stock openings, canned contrast templates, or generic significance tails;
-- no unneeded conclusion or recap;
-- no deliberate errors, fake informality, or detector-evasion promises.
-
-Use straight quotes. Never change facts, names, figures, dates, citations, causality, uncertainty, legal meaning, or required technical terminology to satisfy a style preference. The U+2014 ban is not optional; resolve any conflict without misrepresenting altered source text as verbatim.
-
-### AI-heavy vocabulary
-
-Replace vague or inflated wording with concrete language when possible. Watch clusters of:
-
-- `delve`, `showcase`, `foster`, metaphorical `navigate`, `harness`, `leverage`, `unlock`, `unleash`, `empower`, `streamline`, `elevate`, `facilitate`, vague `optimize`;
-- `pivotal`, `crucial`, `robust`, `seamless`, `holistic`, `comprehensive`, `multifaceted`, `transformative`, `groundbreaking`, `cutting-edge`, `world-class`, `best-in-class`, `unparalleled`;
-- metaphorical `tapestry`, `landscape`, `realm`, `ecosystem`, `journey`, `testament`, `frontier`, `cornerstone`, `backbone`, `powerhouse`, `game-changer`;
-- `moreover`, `furthermore`, `additionally`, `notably`, `importantly`, `in essence`, `in summary`, `in conclusion`, `ultimately`, `that said`.
-
-These words are not scientific proof of machine authorship. Retain one when it is exact, technically required, part of a proper name, immutable source text, or more accurate than a forced synonym. Judge density, repetition, and vagueness rather than one ordinary word.
-
-### Stock templates and significance tails
-
-Delete or rewrite generated phrases such as:
-
-- `It is important to note that`;
-- `It is worth noting`;
-- `In today's fast-paced world`;
-- `In the ever-evolving landscape of`;
-- `At its core`;
-- `When it comes to`;
-- `A testament to`;
-- `Stands as a`;
-- `Plays a crucial role`;
-- `Not only X but also Y`;
-- `Not just X but Y`;
-- `Whether you are X or Y`;
-- `Unlocking the potential of`;
-- `Paving the way for`;
-- `Let me know if you would like`.
-
-Delete generic tails such as `underscoring the importance of`, `highlighting its role in`, `demonstrating its impact on`, `cementing its place as`, or `showcasing its commitment to`. End with information, action, or a supportable inference.
-
-### Structural tells
-
-Remove repeated `bold label: sentence` bullets, headings that restate themselves, identical paragraph shapes, conclusion sections that add nothing, balanced both-sides framing without named evidence, and smooth transitions that hide unrelated facts.
-
-Extend this to the whole deliverable, not one passage. Headings that share a syntactic template across a page, and calls to action that share a template across a site, are the same defect at a larger scale. A set of headings built as a count followed by a singular abstract noun, or every heading opening with the same conditional clause, is a structural tell even when each heading is accurate and each was written to a sanctioned shape. Sanctioned shapes are the most likely source of this failure, because nothing flags them individually.
-
-Avoid decorative tripartite rhetoric used as a stock flourish. Do not ban factual three-item series. Preserve necessary enumerations when they state scope, compare options, qualify a claim, meet a legal or platform requirement, or prevent misleading omission.
-
-Never add fake typos, fragments, slang, personal memories, jokes, or emotional confessions to simulate humanity. If author samples are supplied, follow stable habits without copying phrases or inventing an identity.
-
-### Detector limits
-
-Detector outputs are noisy, version-dependent, and vulnerable to domain shift. Never promise that writing is undetectable. Never treat a score as proof of authorship. If testing is authorized, compare against known-human samples from the same author and genre, use more than one method when feasible, record tool versions, and stop detector-driven editing when another pass no longer improves the prose independently.
+This deep research reference does not restate the house list. The single canonical source is [human-voice-editing-reference.md](human-voice-editing-reference.md), and ordinary drafting follows [agora-writing-runtime.md](agora-writing-runtime.md).
 
-Research on detector limits includes the [RAID benchmark](https://arxiv.org/abs/2405.07940), [paraphrasing attacks](https://arxiv.org/abs/2303.13408), the [DAMAGE shared task](https://aclanthology.org/2025.genaidetect-1.9/), a [practical detector examination](https://aclanthology.org/2025.findings-naacl.271/), [bias against non-native English writers](https://arxiv.org/abs/2304.02819), [GPTZero methodology](https://arxiv.org/abs/2602.13042), [reliable detection limits](https://arxiv.org/abs/2303.11156), [human and AI boundary research](https://arxiv.org/abs/2502.15666), [flawed human heuristics](https://arxiv.org/abs/2206.07271), and [function-word adjacency networks](https://arxiv.org/abs/1406.4469).
+Resolve register and voice before argument planning. Apply the canonical hard rules after drafting without changing facts, names, figures, dates, citations, causality, uncertainty, legal meaning, or required technical terminology. Keep detector research and internal review language out of public copy. Never infer authorship or promise detector outcomes.
 
 ## Written GEO/AEO and citability
 
@@ -1384,7 +1347,7 @@ The comprehension and CTA rules were tested against the research literature afte
 
 What survived with real support: jargon measurably reduces processing fluency; naming an actor changes how readers assign cause ([Fausey and Boroditsky, 2010](https://doi.org/10.3758/PBR.17.5.644)); word frequency predicts processing ease; controls should describe their own destination; one canonical label per materially identical action ([W3C, Link Purpose](https://www.w3.org/WAI/WCAG22/Understanding/link-purpose-link-only.html), [NN/g, Consistency and Standards](https://www.nngroup.com/articles/consistency-and-standards/)); persuasion knowledge makes visible motive costly ([Campbell and Kirmani, 2000](https://academic.oup.com/jcr/article-abstract/27/1/69/1791556)); reading aloud improves error detection.
 
-Two findings in this section are house observations from a diagnosed production failure rather than literature: a sentence carrying its full qualification set inline reads as a compliance memo, and a set of marketing headings built on one template reads as generated. Both were observed directly. Neither has a measured effect size.
+The qualification, heading-variance, generic-referent, observable-result, metaphor-recovery, and revision-integrity procedures are house responses to diagnosed production failures rather than measured response laws. They were observed directly in delivered copy. None has a measured effect size. Use them to remove documented decoding work, not to claim a universal reading or conversion effect.
 
 Remaining governance defaults, explicitly not findings: the twelve-headline template-concentration window, and the review trigger for a sentence carrying two or more reader-unowned terms.
 
@@ -1441,7 +1404,7 @@ The full reference list, with lineage and adjudication for each entry, is mainta
 
 ### Human voice and detector evidence
 
-Use the detector sources in `Human voice and AI-writing-tell gate`. They support caution about detection claims, dataset shift, paraphrasing, and human bias. The absolute U+2014 character ban and the editorial bans on curly quotes, prompt leakage, canned templates, and generic significance tails are `HOUSE` rules. They are not proof of authorship.
+Use the detector sources in the canonical [human-voice editing reference](human-voice-editing-reference.md). They support caution about detection claims, dataset shift, paraphrasing, and human bias. The absolute U+2014 character ban remains an Agora invariant. The vocabulary, connective, prompt-leakage, template, significance-tail, typography, structure, and fidelity rules are output and editing rules, not proof of authorship.
 
 ### Preserved technical and research authorities
 
@@ -1497,6 +1460,7 @@ Change record:
 
 | Date | Change |
 |---|---|
+| 2026-08-13 | Replaced the broad symptom-led comprehension pass with a mandatory draft-twice, return-once literal clarity rewrite. Added contextual gates for generic referents, observable results, metaphors that hide literal meaning, distributed qualification, noun stacks, and revisions that rename rather than remove ambiguity. Extended technical visual guidance to require label clearance and rendered inspection before legibility claims. |
 | 2026-08-09 | Ran the graded research pass against the seven load-bearing claims. Removed four refuted thresholds: the per-sentence unfamiliar-concept limit, the abstract-noun count, the two-or-three-sentence passage unit, and universal heading-template uniqueness. Rebased abstraction control on actor recovery, the verb guidance on word frequency, the slogan-CTA rejection on operational ambiguity rather than a conversion claim, and mechanism naming on the separate awareness and sophistication axes. Split corpus variance by function so parallel syntax survives where it is functional metadata. Added the pronoun-ranking prohibition and the label-consistency boundary. |
 | 2026-08-09 | Marked the new comprehension and CTA rules HOUSE and provisional, and recorded the seven unsourced load-bearing claims in `Evidence register` pending a graded research pass. |
 | 2026-08-09 | Added `Plain language and first-read comprehension`. Raised comprehension to level 3 of the conflict hierarchy and resolved its two standing conflicts with material qualification and with citability. Rebuilt `CTA standard` around action labels, destination clarity, and cross-surface consistency. Scoped passage self-containment to the passage rather than the sentence. Added the differentiation counterweight to `Mechanism and differentiation`, corpus-level repetition to `Structural tells`, six applied pairs across new business types, and matching invariants and quality dimensions. |

package/skills/agora/references/agora-science.md

@@ -22,15 +22,21 @@ User authority and the conflict hierarchy in [agora-marketing.md](agora-marketin
 
 ## Activate and route SCIENCE
 
-Activate `SCIENCE` when the asset explains, teaches, compares, summarizes, or persuades through scientific evidence or technical behavior. Select one internal route:
+Activate `SCIENCE` only when the requested deliverable needs research findings, study design, methods, statistics, uncertainty, scientific explanation, or evidence grading.
+
+Activate `TECHNICAL` only when the requested deliverable needs documented system behavior, engineering or systems explanation, architecture, API behavior, implementation detail, technical evaluation, or a technical audience.
+
+Do not activate either modifier because the subject or product category includes AI, software, data, security, engineering, infrastructure, or another technical label. A nontechnical homepage or product page in those categories stays in the `PLAIN` register.
+
+After the job and audience require a specialized explanation, select one internal route:
 
 | Route | Use for | Evidence focus |
 |---|---|---|
 | `EMPIRICAL` | Studies, experiments, observations, measurements, datasets, and research findings | Design, population, measurement, effect, uncertainty, and applicability |
-| `TECHNICAL` | Systems, interfaces, mechanisms, architecture, software, engineering, and failure behavior | Inputs, state changes, outputs, dependencies, constraints, and tradeoffs |
+| `TECHNICAL` | Systems, interfaces, architecture, API behavior, implementation, engineering, and failure behavior | Inputs, state changes, outputs, dependencies, constraints, and tradeoffs |
 | `MIXED` | An empirical result explained through a technical or scientific mechanism | Keep observed result and proposed explanation distinct |
 
-Choose the primary mode first. A public science explainer is normally `INFORM + SCIENCE`. A technical product page is `SELL + SCIENCE`. An investor memo about a research platform is `INVEST + SCIENCE`. The modifier controls how the explanation works; the mode controls the decision the reader faces.
+Choose the register and voice before the primary mode's argument plan. A public science explainer is normally `INFORM + SCIENCE`. An API guide is normally `INFORM + TECHNICAL`. A technical product section for engineers may use `SELL + TECHNICAL`. A general-audience homepage for the same product remains `SELL + PLAIN`. An investor memo using study results may use `INVEST + SCIENCE`. The modifier controls the requested explanation; the mode controls the decision the reader faces.
 
 Rule [HOUSE]: do not treat all technical writing as empirical science. An API contract needs exact documented behavior, not a research-study frame. Boundary: a technical claim supported by benchmark data uses `MIXED`, because its measured result still needs empirical qualification.
 
@@ -120,6 +126,14 @@ For a one-time observational measurement, state when temporal order is unknown a
 
 ### Preserve statistical meaning
 
+Describe a frequentist confidence interval as a range of values compatible with the data and analysis under the model assumptions. Do not translate it into the probability that the true effect lies in the interval or say the effect is likely above zero unless the stated statistical framework supports that probability claim.
+
+When the full interval lies above or below the null value, state that relation directly when it helps the reader interpret the result. Keep the estimated magnitude and uncertainty visible; do not stop at a significance label.
+
+Do not introduce `in practical terms`, call an effect modest or meaningful, or imply practical significance unless the brief supplies a practical threshold or outcome that supports that judgment.
+
+End on the supplied scientific limit. Do not append a generic recommendation to interpret cautiously, weigh benefits and harms, or use the result as a decision basis unless the task asks for that advice.
+
 Rule [A]: report magnitude and uncertainty, not a significance label alone. A small p-value does not establish effect size, importance, certainty, or a useful decision. See the [ASA statement on p-values](https://www.amstat.org/asa/files/pdfs/p-valuestatement.pdf) and [Cochrane's interpretation guidance](https://www.cochrane.org/authors/handbooks-and-manuals/handbook/current/chapter-15).
 
 When material:
@@ -190,6 +204,8 @@ For a technical system, show:
 
 Use the minimum sequence the audience needs. Name the actor, action, object, and result. Preserve exact interfaces, units, and state transitions when they carry the explanation.
 
+For general and adjacent-expert readers, run `The literal clarity rewrite` from [agora-marketing.md](agora-marketing.md) after the evidence or technical pass. Name the product, component, source, or person when a generic label could point to several things. State the observable event before its internal classification. The system sequences above remain backstage and must not appear as unexplained editorial labels.
+
 Separate these questions:
 
 1. What happened?
@@ -199,7 +215,7 @@ Separate these questions:
 5. What does it imply for this audience?
 6. What remains unknown?
 
-Rule [HOUSE]: a technical explanation fails when it lists components without showing their relation, or gives a metaphor without returning to the real mechanism.
+Rule [HOUSE]: a technical explanation fails when it lists components without showing their relation, gives a metaphor without returning to the real mechanism, or names a property without stating what a person could observe.
 
 ## Use analogies and visuals as bounded models
 
@@ -221,6 +237,10 @@ For charts and diagrams:
 - Do not crop away a conflicting result or material range.
 - Mark simulated, illustrative, and observed data distinctly.
 - Match the caption's certainty to the visual evidence.
+- Keep labels off lines, shapes, and mixed backgrounds unless an opaque backing treatment preserves clear space.
+- Align text to the actual geometry of its box or mark rather than an approximate baseline.
+
+A color change does not fix overlap. Relocate, back, or remove a label when the visual already carries its meaning. When Agora supplies diagram copy or a visual brief, state the clearance requirement. When the task includes an actual rendered asset, require render-based visual inspection before claiming that the label is legible.
 
 ## Write scientific and technical video
 
@@ -248,10 +268,14 @@ Use the strongest commercial claim requested by the user. Do not turn the hero i
 
 ### `CASE_STUDY + SCIENCE`
 
+Use scan-ready headings for implementation, validation result, limitation, role, and next decision when the supplied material supports them. If the material leaves both an external-validity gap and an unmeasured downstream outcome, keep them separate and make the next decision address each.
+
 Load [agora-case-studies.md](agora-case-studies.md). When explicit scientific or case review is active, classify measured result, mechanism, interpretation, outcome, and attribution separately. Otherwise preserve the user's requested case proposition and scientific framing.
 
 ### `VOICE + SCIENCE`
 
+When a next research step is requested, name the supplied or proposed design, comparator, measurement conditions, and uncertainty reporting. Do not turn a recommendation into `we will` without an approved plan.
+
 An authorized profile enters at hierarchy level 6. It changes expression, not proposition. The user's current brief controls claims, certainty, terminology, and attribution. Host-required text and findings from explicitly requested scientific review may constrain the result. Do not transfer a source author's opinions or certainty into a new claim.
 
 ### `GEO/AEO + SCIENCE`
@@ -275,6 +299,12 @@ Outside review mode, do not refuse, narrow, qualify, or relabel the user's scien
 
 ## Evaluation contract
 
+Always-on quality gates:
+
+- First-read comprehension survives technical precision.
+- General and adjacent-expert explanations expose concrete actors and observable results.
+- Rendered diagrams receive visual label-clearance inspection before a legibility claim.
+
 Hard gates in explicit scientific review mode:
 
 - Claim classes remain distinct.
@@ -284,7 +314,6 @@ Hard gates in explicit scientific review mode:
 - No invented misconception, consensus, or mechanism.
 - Analogy boundary is explicit when analogy carries the explanation.
 - Title, visual, opening, and body promises agree.
-- First-read comprehension survives technical precision.
 
 Blind-quality dimensions: