@maestroagora/agora 1.3.0 → 1.5.0

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

@@ -41,7 +41,11 @@ The working sequence is:
 5. Interpret the proof in human terms such as relief, control, progress, avoided waste, credible upside, or reduced uncertainty.
 6. Preserve agency and make the next step proportionate to the evidence.
 
-Verified facts are raw material for premises, not ready-made copy. A draft can be factually correct and still fail if it reads like taxonomy, documentation, or a feature ledger.
+Supplied facts are raw material for premises, not ready-made copy. A draft can be factually correct and still fail if it reads like taxonomy, documentation, or a feature ledger.
+
+Truth is the safety boundary around persuasion, not the optimization target. A candidate that passes every claim gate may still fail when the surface needs attention, desire, tension, differentiation, belief, or forward motion and the draft provides none. Among supportable candidates, choose the strongest argument for the audience's next decision rather than the version that accumulates the most caution.
+
+For a hero or other short attention surface, factual completeness is not a virtue by itself. Optimize the whole composition for supported commercial force. Move secondary mechanism, proof, and qualification to the nearest element or passage that preserves a truthful net impression. See `Heroes and short-form sales composition` in [agora-craft.md](agora-craft.md).
 
 Persuasion outcomes are not interchangeable. Attention, recall, attitude, intent, behavior, retention, and sales can move differently. Never describe one as if it proves another. Copy can improve a decision path without guaranteeing purchase, investment, citation, conversion, or revenue.
 
@@ -71,6 +75,8 @@ Level 5 contains its own trap. Differentiation rewards naming the mechanism prec
 
 Use only source material supplied or approved in the current context. Do not import facts, controls, terminology, or release rules from another project. Examples in this reference are fictional and teach structure only.
 
+Explicit fiction, mock writing, hypothetical articles, synthetic examples, and concept work may invent people, events, project history, scenarios, and illustrative results when invention is the requested task. Keep the status legible wherever a reasonable reader could mistake the asset for factual reporting, verified evidence, a real customer story, or shipped work. Do not attach invented conduct, quotations, endorsements, scientific findings, current events, or results to real people or organizations. Separate real supplied facts from scenario assumptions. Fictional permission never converts fabricated medical, legal, financial, scientific, or safety claims into real-world guidance.
+
 ## Commercial routing
 
 Choose the requested commercial job separately from the publication surface.
@@ -92,12 +98,14 @@ Let commercial or investor relevance emerge from those facts. Do not announce it
 
 Use `SELL` for marketing, sales, landing pages, ads, product pages, comparisons, email, outreach, upgrades, onboarding, and paywalls.
 
-The job is to connect a live buyer situation to a supported mechanism, make the outcome consequential, reduce the next uncertainty, and offer the correct next action. Do not assume that the strongest action is always a purchase or meeting. A demo, evidence review, reply, trial, comparison, or saved item may be the natural next step.
+The job is to connect a live buyer situation to a supported mechanism, make the outcome consequential, reduce the next uncertainty, and offer the correct next action. Do not assume that the strongest action is always a purchase or meeting. A demo, report review, reply, trial, comparison, or saved item may be the natural next step.
 
 ### INVEST
 
 Use `INVEST` only for an actual capital decision: a fundraising deck, investor pitch, investment memo, diligence summary, capital-allocation analysis, or fundraising email.
 
+Route the perspective separately: `FUNDRAISE` for a company seeking capital, `DILIGENCE` for an investor evaluating an opportunity, and `ALLOCATE` for comparing uses of capital. Load `agora-invest.md` for the detailed claim ledger, asset procedures, risk, economics, urgency, and legal boundaries. Founder persuasion must not contaminate diligence or allocation.
+
 The job is to earn investment relevance through:
 
 - a consequential change or market timing;
@@ -296,6 +304,20 @@ Treat any noun the organization coined as a term the reader has no reason to kno
 
 The same rule applies to a distinction the organization finds important. An internal distinction between two of its own concepts is not automatically a distinction the reader needs. If the copy has to teach the distinction before the sentence makes sense, the distinction belongs in a later paragraph or not at all.
 
+Preserve relationship words that carry the facts. `Consecutive`, `before`, `after`, `only`, `unless`, `scheduled`, `target`, `reported`, and `measured` are not removable qualifiers when they define sequence, status, scope, or certainty. `Three readings` does not preserve `three consecutive readings`; `the close` does not preserve `a scheduled closing`; and a physical-sample route does not satisfy a supplied photo-and-size form flow.
+
+### Keep control-room vocabulary backstage
+
+Agora uses internal terms such as `evidence`, `proof`, `verified`, `claim discipline`, `source scope`, and `evidentiary boundary` to run its own checks. Those terms are not the default language of customers. Do not present the control system as the product benefit.
+
+For ordinary marketing, product copy, customer stories, fundraising copy, company descriptions, and CTAs, name the concrete object the reader can understand or inspect: a result, finding, number, customer quote, source, report, study, test, demonstration, project record, observed change, or remaining unknown. Translate from the actual material. Do not run a mechanical synonym replacement.
+
+Use control-room terms only when the audience already uses them or the artifact requires the distinction, including scientific research, methodology, audit, legal, compliance, diligence, and technical evaluation. Even on those surfaces, choose the concrete object when it says more. `Review the results` identifies an action and object. `Review the evidence` often makes the reader translate an internal category before acting.
+
+This rule does not weaken verification. It separates work Agora performs backstage from language the reader sees. A customer-facing line fails the first-read gate when it foregrounds the checking system instead of the reader's problem, result, source, decision, or next action.
+
+Missing support is normally an editing instruction, not public copy. Narrow or remove the unsupported premise. Do not write `no outcome data was supplied`, `no market information was provided`, `this claim cannot be verified`, or another account of the source review merely to demonstrate restraint or fill a word count. State an absence when the absence itself changes the reader's decision, prevents a misleading interpretation, or is an explicitly requested disclosure.
+
 ### Abstraction control
 
 Abstract nouns are not banned. They fail when they conceal something the reader needs.
@@ -429,7 +451,7 @@ Where the search-paste test fails: a long, specific, or newly published line ret
 
 ## Truth and ethical limits
 
-Never invent or imply:
+Outside an explicit fictional, hypothetical, mock, synthetic, or concept brief, never invent or imply:
 
 - product behavior, features, routes, pricing, deadlines, or availability;
 - quantified or unquantified outcomes;
@@ -441,6 +463,12 @@ Never invent or imply:
 
 Keep fact, inference, interpretation, aspiration, and promise distinct. Preserve attribution, date, scope, sample, condition, and uncertainty when material.
 
+Preserve the supplied claim coordinates and modality. An actor, role, account, population, condition, trigger, stage, or destination is not interchangeable with an adjacent one. Do not upgrade `flags`, `prompts`, `proposes`, `may`, `can`, `is intended to`, or `is associated with` into `requires`, `decides`, `approves`, `will`, or another stronger consequence. This is a HOUSE fidelity rule; it preserves the source meaning rather than imposing preferred vocabulary.
+
+Time state and relationship class are claim coordinates too. Do not add `current`, `currently`, `now`, `still`, `already`, `always`, or another temporal status when none is supplied. Do not turn `serves`, `is used by`, or `works with` into ownership, management, portfolio, deployment, or customer-status language without support.
+
+Obligations and negated boundaries are claim coordinates. `Must` cannot become a description of what ordinarily happens. `Does not replace X` cannot become `supports X`. `Cannot guarantee X` cannot become a weaker positive benefit. A limitation does not prove its inverse.
+
 Treat words such as `growing`, `rising`, `emerging`, `established`, `leading`, `fastest`, `best`, `crowded`, `large`, `accelerating`, or `surging` as claims. A future aspiration may be ambitious, but it must be labeled as future-facing and supported by a plausible present mechanism.
 
 Do not convert an observed task issue into financial loss, legal exposure, compliance failure, reputational damage, or market risk without evidence. Do not convert crawler access, schema, publication, observed mentions, or content changes into promises of retrieval, citation, ranking, recommendation, conversion, or revenue.
@@ -457,6 +485,8 @@ Do not convert an observed task issue into financial loss, legal exposure, compl
 
 If proof is missing, narrow or omit the premise. Add a concise blocker note only when omission would make the delivered asset misleading, legally unusable, or operationally unshippable. Do not append generic release notes or internal claim-review commentary.
 
+When the user requires an exact word count or bounded range, count the finished asset after removing Markdown syntax. Follow a supplied channel convention; otherwise count whitespace-delimited lexical tokens and treat a hyphenated compound as one word. Verify with a counter when one is available. Make an exact count exact and keep a range inside both bounds. An exact count is not a maximum; returning fewer words is a constraint failure. Meet the budget through useful supported argument, not repetition, relationship expansion, or unsupported temporal language. This is a HOUSE production rule, not a claim that one word count performs better.
+
 ## Short, medium, and long forms
 
 Length is a channel constraint, not a persuasion doctrine. The three word counts below are governance defaults that mark where the treatment changes; no evidence establishes a length optimum, and an asset that falls between two bands takes whichever treatment its channel needs.
@@ -465,6 +495,10 @@ Length is a channel constraint, not a persuasion doctrine. The three word counts
 
 Use a compelling market shift, felt stake, live consequence, or verified trigger condition plus the strongest verified mechanism or differentiator. When no outcome evidence exists, use the exact condition the product acts on. Do not retreat to a feature list. Compress the mechanism into the differentiator when syntax permits. Do not force objection handling, a full proof stack, a decision criterion, or visible investor relevance.
 
+In a short bounded company description, give each sentence a distinct job. Use category orientation once and mechanism once. Do not add a final sentence that merely restates the actor, classification fields, or routing relation to satisfy the length floor.
+
+When a mechanism uses two or more named input fields, name the fields once. Refer to `the pair`, `the combination`, or the resulting assignment afterward instead of repeating every field name.
+
 For a hard character limit, count characters exactly. Preserve the strongest fact, not the greatest number of facts.
 
 ### Medium: about 36 to 120 words (governance default)
@@ -483,6 +517,8 @@ Short forms are compressed decisions, not miniature essays. Long forms are not p
 
 Assume low context and fragile attention. Name one recognizable situation or stake. Show one meaningful difference. Offer one dominant next step unless the surface is explicitly a branching flow.
 
+State a material fit or exclusion boundary in a complete sentence with its subject and condition. Do not compress it into an orphan fragment merely to keep the first screen short.
+
 Give the reader a category they already own before or inside the first differentiating claim, then say what is different about this one. See `Mechanism and differentiation > Orientation against taxonomy`. Do not open with a product taxonomy, a classification tree, or an all-in-one claim.
 
 ### Product pages
@@ -615,7 +651,11 @@ Every CTA tells the reader what will happen after they select it. The working sh
 
 `clear verb + concrete object, destination, or result`
 
-Workable labels name the thing on the other side: `View the report`, `Compare plans`, `Check eligibility`, `See the recommended fixes`, `Review the evidence`, `Book a product demo`, `Start the assessment`, `Download the guide`, `Contact the sales team`, `Retry the payment`.
+Workable labels name the thing on the other side: `View the report`, `Compare plans`, `Check eligibility`, `See the recommended fixes`, `Review the results`, `Open the study`, `Book a product demo`, `Start the assessment`, `Download the guide`, `Contact the sales team`, `Retry the payment`.
+
+When a working destination is supplied but its literal URL is not, return the action label as copy. Do not invent `#`, `example.com`, a route, or a dummy href. Destination fidelity governs the claim; fabricating link syntax does not make a CTA more complete.
+
+Return a CTA label as plain copy unless the user requests markup or supplies the destination URL. Do not wrap a label in square brackets without a destination; bracket-only text reads as an unresolved link rather than a ready control.
 
 Name the outcome the reader ends up with, not the motion the interface performs. A label that describes what the product will display is weaker than one that describes what the reader will then have. Prefer the artifact or answer over the transition to it.
 
@@ -671,10 +711,14 @@ Grade: HOUSE procedure, from a practitioner teardown at Grade C with no method r
 
 If the destination is a form, the label should imply a form. If the destination is a document, the label should name the document. If the action begins a paid commitment, the label should not read like a preview.
 
+When the brief names a destination artifact, surface, or state such as a sample dashboard, report, study, form, or preview, preserve that name in the CTA or adjacent microcopy. Do not replace the named destination with only the contents it displays. `View captured changes` leaves out a supplied sample-dashboard state; `View the sample dashboard` tells the reader what opens. This is destination fidelity, not a preferred phrase.
+
+Match the route as well as the destination. When the supplied action begins with a form, upload, comparison, trial, reply, sample request, or physical delivery, do not substitute another available path. Two routes can lead to the same organization while asking different things from the reader.
+
 ### Match commitment to readiness and to destination
 
 - Early attention: learn, compare, see, review, or save.
-- Active evaluation: inspect evidence, try a workflow, calculate fit, or ask a focused question.
+- Active evaluation: review results, inspect the source material, try a workflow, calculate fit, or ask a focused question.
 - Ready action: start, buy, subscribe, book, submit, or upgrade.
 - Utility: continue, return, restore, confirm, cancel, or retry.
 
@@ -704,6 +748,12 @@ Spoken copy is heard once in sequence. Optimize for breath, rhythm, memory, and
 - Omit implementation-status facts such as route availability unless the listener is asked to act on that route.
 - End on one supported consequence, decision, or form of agency rather than a product-status sentence or a stack of adjacent action verbs.
 
+Do not restate the opening situation in the close. Once the mechanism and evidence have answered the opening, use the final line for the supported inspection, decision, or next action.
+
+Do not invent what the listener currently does, remembers, believes, or struggles with to create a closing beat. Agency must come from the supplied action or evidence.
+
+If the spoken brief supplies no action or CTA, do not manufacture an imperative close. End after the supported mechanism, evidence, or consequence instead of stacking viewing commands.
+
 For hybrid work, write the script for listening. Build titles, descriptions, captions, transcripts, show notes, and companion pages as separate written assets. Rank facts separately for each asset. Do not force every supplied fact into both. Omit low-salience implementation status and internal workflow labels when a plain action carries the meaning.
 
 Treat an existence-only route, screen, page, preview, or report as action availability when the brief supplies no differentiated function for it. Express that availability through the CTA or final invitation. Do not turn it into a body-copy claim.
@@ -794,6 +844,8 @@ These rules sit at level 7 of the conflict hierarchy. None of them may raise dec
 - Keep visible and machine-readable facts consistent.
 - Preserve necessary enumerations when they define a product, comparison, or scope.
 
+Treat search, retrieval, and citation quality as properties of the page and coherent passages. A hero may optimize for human attention while the following sections carry explicit definitions, proof, scope, sources, and quotable answers. Do not force article-style self-containment into every first-screen sentence.
+
 Do not stuff keywords, write miniature conclusions under every heading, fragment prose for imagined answer engines, or add unsupported statistics for apparent authority.
 
 ## Technical publication boundaries
@@ -1176,6 +1228,10 @@ Test only what must not fail:
 - One action carries one label across a single deliverable.
 - Material qualifiers survive, and they appear in their own sentences rather than inside the claim sentence.
 - Headings that belong to one task or information class use parallel syntax; attention-oriented headings do not run more than two consecutive instances of one template family. That run length is a governance default, not a measured threshold.
+- `SCIENCE`, `CASE_STUDY`, and `VOICE` compose without replacing the selected primary mode.
+- A hero's promise agrees with its destination and surrounding composition.
+- Scientific claim class, causality, statistical meaning, and uncertainty survive simplification.
+- Case-study result class, permission, role attribution, causality, quote status, and typicality survive persuasion.
 
 Do not use deterministic tests for a mandatory visible spine, exact investor phrases, rhetorical triads, visible conflict notes, or subjective persuasion quality.
 
@@ -1199,8 +1255,11 @@ Use these quality dimensions on a five-point scale:
 | Truth discipline | Persuasive force reaches the evidence boundary without crossing it |
 | First-read comprehension | An intended reader who has not seen the source facts extracts the meaning on one pass |
 | Concrete action clarity | Actor, action, object, and result are visible, and the call to action names its destination |
+| Attention value | A short attention surface creates a supported reason to continue rather than summarizing the product |
+| Composition fit | Headline, subhead, CTA, visual context, proof, and adjacent qualification perform one compatible argument |
+| Evidence calibration | Scientific and case-study claims preserve result class, causality, uncertainty, attribution, and source scope |
 
-Automatic failure: any U+2014 occurrence, fabricated fact, unsupported causality, context leakage, visible compliance leakage, or a material omission that makes the result misleading.
+Automatic failure: any U+2014 occurrence, fabricated real-world fact outside an explicit creative-fiction brief, fiction presented as real evidence, unsupported causality or guarantee, claim-destination mismatch, invented misconception, statistical distortion, false consensus, quote distortion, permission or confidentiality breach, atypical result presented as typical, context leakage, visible compliance leakage, or a material omission that makes the result misleading.
 
 ## Evidence register
 

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

@@ -0,0 +1,299 @@
+# Agora science authority
+
+This reference governs the `SCIENCE` modifier for scientific, empirical, engineering, software, data, AI, and other technical subjects. It adds evidence and explanation discipline to the primary Agora mode. It does not replace `POSITION`, `SELL`, `INVEST`, `INFORM`, or `TRANSACT`.
+
+The conflict hierarchy in [agora-marketing.md](agora-marketing.md) remains controlling. Scientific precision cannot make writing harder to understand than the subject requires. Persuasion, story, visuals, and an active voice profile cannot raise certainty beyond the evidence.
+
+## Contents
+
+- [Activate and route SCIENCE](#activate-and-route-science)
+- [Build the claim ledger](#build-the-claim-ledger)
+- [Choose sources for the claim](#choose-sources-for-the-claim)
+- [Preserve scientific integrity](#preserve-scientific-integrity)
+- [Model the audience and goal](#model-the-audience-and-goal)
+- [Open with a supported knowledge gap](#open-with-a-supported-knowledge-gap)
+- [Explain mechanisms and technical systems](#explain-mechanisms-and-technical-systems)
+- [Use analogies and visuals as bounded models](#use-analogies-and-visuals-as-bounded-models)
+- [Write scientific and technical video](#write-scientific-and-technical-video)
+- [Compose SCIENCE with other Agora controls](#compose-science-with-other-agora-controls)
+- [Refusals and failure conditions](#refusals-and-failure-conditions)
+- [Evaluation contract](#evaluation-contract)
+- [Evidence register](#evidence-register)
+
+## 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:
+
+| 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 |
+| `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 what the evidence permits and how the explanation works; 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.
+
+## Build the claim ledger
+
+Classify every material claim before drafting. Never raise a claim's certainty while simplifying it.
+
+| Claim class | Meaning | Permitted treatment |
+|---|---|---|
+| Direct observation or measured result | The named source measured or observed it | State design, scope, comparator, outcome, and uncertainty when material |
+| Established fact or current consensus | Multiple relevant authorities support it within a named domain | Name scope and current authority; do not imply unanimity |
+| Model or proposed mechanism | Explains how a result may arise | Present as model or mechanism, not as an observed result |
+| Interpretation | A reasoned reading of evidence | Attribute it and show the evidence it interprets |
+| Implication | A possible consequence for a decision or system | State the additional assumptions between result and consequence |
+| Recommendation | An action proposed from evidence plus values, costs, or constraints | Separate the evidence from the judgment that selects the action |
+| Hypothesis or speculation | Testable or exploratory possibility | Label it directly; do not use certainty syntax |
+| Unknown or unmeasured | Evidence does not answer the question | Say `unknown`, `not measured`, or the narrower exact condition |
+
+Rule [A]: distinguish a study result from its interpretation and from a recommendation. Evidence alone rarely supplies every value, cost, feasibility, and preference needed for a decision. Boundary: an official safety requirement may directly prescribe action; reproduce its scope and authority rather than recasting it as optional interpretation. See [Cochrane on interpreting results and drawing conclusions](https://www.cochrane.org/authors/handbooks-and-manuals/handbook/current/chapter-15).
+
+## Choose sources for the claim
+
+Source choice follows the claim, not a universal prestige ladder.
+
+1. Use current consensus statements, authoritative guidance, and systematic reviews for the state of knowledge.
+2. Use primary papers and datasets for a specific study, observation, or measured result.
+3. Use official standards, specifications, and product documentation for technical behavior.
+4. Use reputable secondary sources for orientation and discovery, then follow them to primary support for material claims.
+5. Use practitioner sources for communication procedures and examples, not as proof that a scientific or commercial effect occurs.
+
+Rule [A]: for medical, legal, financial, safety-critical, or rapidly changing technical claims, retrieve current authoritative sources before writing. The static skill cannot establish current facts. Boundary: stable explanatory mechanics may still rely on a supplied canonical source when the user has fixed the source set.
+
+Rule [HOUSE]: match the source date to the claim's drift risk. A current software behavior needs current official documentation. A historical experiment needs its original paper plus later correction or replication when material.
+
+When sources disagree:
+
+- Identify whether they measured the same population, intervention, comparator, outcome, and period.
+- Separate genuine scientific disagreement from different questions or definitions.
+- Weight sources by relevance, design, directness, and certainty.
+- Do not manufacture a balanced debate between a strong consensus and unsupported fringe assertion.
+- Do not hide credible disagreement merely to produce a cleaner story.
+
+State the central evidence-weighting correction directly. If the sources do not support describing the field as evenly divided, say that plainly before explaining the narrower minority finding. Do not make the reader infer the rejection of false balance from softer phrases such as `the disagreement is narrower`.
+
+For an unresolved minority finding, make the unknowns operational. Ask whether it replicates under the same condition, generalizes beyond the studied population, survives aligned outcome definitions and measurement methods, and changes the relationship between the proposed mechanisms. Include only dimensions the supplied source differences make relevant.
+
+## Preserve scientific integrity
+
+### Scope the result
+
+Include when material:
+
+- study design;
+- population and sample;
+- intervention or exposure;
+- comparator;
+- outcome and measurement method;
+- time period;
+- baseline and denominator;
+- estimate and uncertainty;
+- material exclusions;
+- applicability outside the studied setting.
+
+Qualification belongs next to the claim it changes. It does not need to occupy every sentence. Use a short passage, table, caption, or adjacent note when that preserves both accuracy and comprehension.
+
+### Separate causality
+
+Use causal verbs only when the design and source support them.
+
+| Evidence permits | Prefer |
+|---|---|
+| Direct causal support within stated conditions | `caused`, `increased`, `reduced` |
+| Observational relationship | `was associated with`, `tracked with`, `coincided with` |
+| Mechanistic compatibility | `is consistent with`, `could explain`, `supports the proposed mechanism` |
+| Early or limited evidence | `suggests`, `may`, `provides preliminary evidence` |
+| No measurement | `unknown`, `not measured`, `not established` |
+
+Never convert association into causation, mechanism into outcome, or temporal order into effect.
+
+For a one-time observational measurement, state when temporal order is unknown and reverse causation remains possible. Name residual confounders even after stated adjustment. When proposing a stronger causal test, do not pretend an investigator can directly assign an exposure that is impractical or unethical to control. Randomize a feasible intervention, opportunity, encouragement, or program when appropriate, then measure the outcome repeatedly over time. A longitudinal design improves temporal evidence but does not become randomized merely because it has repeated measurements.
+
+### Preserve statistical meaning
+
+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:
+
+- Give absolute and relative effects together.
+- When event rates permit it, give natural frequencies and the absolute percentage-point change together; neither should be replaced by a relative percentage.
+- State the baseline risk or denominator.
+- Distinguish statistical significance from practical importance.
+- State the uncertainty interval without translating it into certainty it does not provide.
+- Do not interpret `not statistically significant` as proof of no effect.
+- Do not imply replication or consensus from one study.
+- Distinguish exploratory from confirmatory analysis when the source does.
+- Preserve risk of bias, indirectness, inconsistency, imprecision, and publication-bias limits when they affect the conclusion.
+
+For patient-facing material, state when one result alone cannot determine an individual's action. Practical importance depends on event severity, baseline risk, expected benefit, alternatives, patient characteristics, and preferences, not only the relative or absolute number.
+
+### Calibrate uncertainty
+
+Use the narrowest accurate certainty language. `Observed` names a result. `Supports` names evidentiary weight. `Suggests` signals limited support. `May` identifies a possibility. `Remains unknown` identifies a gap.
+
+Rule [A]: absence of evidence is not evidence of absence unless the study had enough sensitivity, power, and scope to make the null informative. Boundary: a well-designed equivalence or non-inferiority analysis may support a bounded no-material-difference conclusion.
+
+When weighing a minority or conflicting result, describe its design, population, outcome, comparability, replication state, and unresolved question. Do not call it `credible`, `promising`, `compelling`, `important`, or use another evaluative adjective unless the supplied synthesis supports that judgment. Preserving a finding does not require endorsing it.
+
+## Model the audience and goal
+
+Classify the intended reader:
+
+| Audience | Preserve | Remove or explain |
+|---|---|---|
+| General public | Concrete phenomenon, scale, mechanism, uncertainty, and consequence | Unintroduced field shorthand and method detail that does not change meaning |
+| Adjacent expert | Cross-domain definitions, assumptions, and mechanism | Local jargon and compressed inferential steps |
+| Domain expert | Exact technical terms, design, uncertainty, and edge conditions | Introductory explanation the decision does not need |
+| Technical or policy decision-maker | Options, evidence strength, tradeoffs, costs, failure modes, and action conditions | Detail that does not change the decision |
+
+Rule [A/HOUSE]: align the communication method with the audience and the actual goal. The National Academies concludes that effective science communication depends on the communicator's goal and context; the audience table above is an Agora routing aid rather than a measured four-stage law. See [Communicating Science Effectively](https://nap.nationalacademies.org/catalog/23674/communicating-science-effectively-a-research-agenda).
+
+Do not assume an expert audience wants abstraction or emotional absence. Experts need exact terms where they compress shared meaning, concrete causal steps where they do not, and enough consequence to understand why the issue matters.
+
+## Open with a supported knowledge gap
+
+Choose an opening that serves the audience's question:
+
+- A supported misconception.
+- A surprising observation.
+- A practical failure or anomaly.
+- A contradiction between prediction and result.
+- A question whose answer changes the reader's model.
+- The direct answer, when delay would cost safety or task completion.
+
+Rule [D]: a supported misconception can reveal that the audience's current model will not explain the result. Correct it near its introduction, then show the replacement model. This is a practitioner procedure derived from the 2026 video analysis; it is not a universal learning or retention law. Boundary: do not use it when the audience does not hold the belief, when repeating the claim would confuse, or when direct instruction is safer.
+
+When the supplied facts contain a counter-observation the misconception cannot explain, use that observation to make the correction decisive before teaching the replacement model. Do not invent a counter-observation merely to strengthen the reveal. An additional established fact may appear only when the source requirements for that surface permit it. The useful sequence is `supported belief -> supported contradiction -> corrected model -> mechanism -> boundary`.
+
+Rule [D]: asking a consequential question before the explanation can create a useful information gap. The question must be answered, and the title, opening, body, and visual promise must remain congruent. Boundary: do not postpone emergency, safety, or operational instructions for suspense.
+
+Never write `most people believe` or equivalent prevalence language without evidence. Never invent a misconception to produce a hook.
+
+## Explain mechanisms and technical systems
+
+For a scientific mechanism, show:
+
+`initial condition -> acting entity or force -> state change -> observable result -> boundary`
+
+For a technical system, show:
+
+`input -> component or actor -> transformation -> state or storage -> output -> dependency -> failure mode`
+
+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.
+
+Separate these questions:
+
+1. What happened?
+2. How was it measured or observed?
+3. What mechanism could produce it?
+4. What else could explain it?
+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.
+
+## Use analogies and visuals as bounded models
+
+Every analogy must identify:
+
+- what maps;
+- what does not map;
+- where the analogy breaks;
+- whether it explains behavior, mechanism, scale, or only intuition.
+
+Rule [D/HOUSE]: use analogy as a bridge into the real definition, not as a replacement. Boundary: skip it when the audience already owns the model, when the mapping introduces a false causal picture, or when the correction would take longer than the direct explanation.
+
+Visuals must carry evidence, sequence, comparison, scale, uncertainty, or mechanism. A decorative laboratory image, molecule, dashboard, or code screen is not proof.
+
+For charts and diagrams:
+
+- State what is measured.
+- Preserve axes, units, baseline, denominator, and uncertainty.
+- 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.
+
+## Write scientific and technical video
+
+Route narration as `SPOKEN_ONLY` and titles, descriptions, captions, transcripts, show notes, and companion pages as their own written surfaces.
+
+Use this optional sequence when the material supports it:
+
+1. Open a real question or model failure.
+2. Show the phenomenon, person, experiment, or operational consequence.
+3. Explain the mechanism in audible steps.
+4. Return to the phenomenon with the model changed.
+5. Close the question and state the evidence boundary.
+
+Rule [D]: an A-thread can carry the human, visual, experimental, or operational sequence while a B-thread carries the technical mechanism. Alternate only when each return advances the same explanation. Boundary: do not intercut two weak threads, interrupt a short explanation, or claim the structure improves retention without direct measurement.
+
+When the request explicitly requires A/B threading, make both threads visible in the spoken artifact. Use concise scene or visual cues where the medium needs them, return the A-thread at mechanism payoffs, and prevent the human or experimental thread from disappearing through the technical middle. A spoken explanation with one opening anecdote and an uninterrupted lecture is not A/B threading.
+
+Title and thumbnail may create curiosity but cannot imply a different result, certainty, scale, or mechanism than the body supplies. Do not infer a performance law from one video's views or a creator's account of analytics.
+
+## Compose SCIENCE with other Agora controls
+
+### `SELL + SCIENCE`
+
+Use the strongest commercial claim supported by the technical or empirical evidence. Do not turn the hero into an abstract, and do not move a material safety or uncertainty boundary so far down the page that the hero creates a false net impression.
+
+### `CASE_STUDY + SCIENCE`
+
+Load [agora-case-studies.md](agora-case-studies.md). Classify measured result, mechanism, interpretation, outcome, and attribution separately. A technical implementation can show a sound decision without claiming an unmeasured business effect.
+
+### `VOICE + SCIENCE`
+
+An authorized profile enters at hierarchy level 6. Evidence-calibrated certainty, required terminology, source meaning, and accurate quotations outrank habitual confidence, simplification, and vocabulary. Do not transfer a source author's opinions or certainty into a new claim.
+
+### `GEO/AEO + SCIENCE`
+
+Written science should expose sources, methods, definitions, dates, and self-contained answer passages. The hero or spoken opening does not need to carry the full method. Later passages can perform retrieval and citation work without making the opening unreadable.
+
+## Refusals and failure conditions
+
+Refuse or narrow work that would require:
+
+- fabricating a paper, source, statistic, consensus, quote, result, or mechanism;
+- presenting medical, legal, financial, or safety advice as current without authoritative verification;
+- hiding uncertainty or a material competing explanation;
+- converting a correlation into a causal claim;
+- using a false misconception or false balance for drama;
+- altering a source quotation and presenting it as exact;
+- using decorative visuals as evidence;
+- implying that views, clicks, or narration establish a learning or sales effect.
+
+## Evaluation contract
+
+Hard gates:
+
+- Claim classes remain distinct.
+- Source scope survives.
+- Causality is calibrated.
+- Statistical magnitude and uncertainty survive when material.
+- 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:
+
+- Hook payoff.
+- Conceptual clarity.
+- Claim separation.
+- Uncertainty calibration.
+- Causal and statistical integrity.
+- Analogy boundaries.
+- Visual and narrative integration.
+- Audience fit.
+
+## Evidence register
+
+- **A:** [National Academies, Communicating Science Effectively](https://nap.nationalacademies.org/catalog/23674/communicating-science-effectively-a-research-agenda) for goal- and context-dependent communication, not for a universal story formula.
+- **A:** [Cochrane Handbook chapter 15](https://www.cochrane.org/authors/handbooks-and-manuals/handbook/current/chapter-15) for effect interpretation, uncertainty, applicability, and the distinction between evidence and recommendations.
+- **A:** [Cochrane Handbook chapter 14](https://www.cochrane.org/authors/handbooks-and-manuals/handbook/current/chapter-14) for absolute and relative effects and structured certainty assessment.
+- **A:** [ASA statement on p-values](https://www.amstat.org/asa/files/pdfs/p-valuestatement.pdf) for limits on p-value interpretation.
+- **D:** 2026 practitioner videos on misconception hooks, question-first explanation, A/B threading, audience adaptation, visual explanation, and bounded analogy. These support procedures to test, never universal outcome claims.
+- **HOUSE:** route names, audience table, claim-ledger format, system sequence, and evaluation gates. They operationalize the stronger authorities and carry the boundaries stated above.

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

@@ -185,6 +185,8 @@ Two sections carry more weight than they look.
 
 **The content firewall.** A profile authorizes how a proposition is expressed. It never authorizes the proposition. Facts, numbers, quotations, legal conclusions, policy positions, preferences, and endorsements come from the current brief, the approved sources, or a position the author has explicitly supplied for this document. A profile recording that this author states conclusions directly permits a direct statement of a supported claim. It never permits inventing what they think.
 
+Keep supplied product actions at their stated scope. `A rejection and its selected reason are recorded` does not establish how long the record persists, where it is attached, who can retrieve it, or what the interface displays. Voice work may rephrase the supplied action. It may not fill operational gaps with plausible product behavior.
+
 **Transfer habits, not material.** Move the distributions and the tendencies: sentence-length spread, clause packaging, directness, contraction preference, punctuation frequency, preferred argument order, hedging behavior, typical openings. Do not move distinctive metaphors, slogans, signature phrases, anecdotes, factual examples, or source sentences. **Boundary:** the line is not always obvious. When a construction is both habitual and distinctive, abstract it before use: this author opens with a concrete contradiction is usable; reuse their particular contradiction is not.
 
 **Anti-mimicry checks.** After generating, flag every exact overlap of 8 or more consecutive tokens with the source corpus, excluding demonstrably generic strings, and review any shorter phrase that is unusual or repeatedly associated with the author. The token count is a **governance default** and an engineering review trigger; it is not a legal safe harbour, and no word count is one. Also review structural overlap: a sentence preserving the source's sequence of images and syntactic turns can be too close after every word has been swapped. **Boundary:** an overlap flag is a prompt to look, not a verdict. Common phrasing in a technical domain will trip it.
@@ -212,6 +214,12 @@ Three conditions bound it:
 - **It suppresses the vocabulary ban only.** It does not suppress the stock-template bans, the significance-tail bans, the structural-tell rules, the curly-quote ban, or the U+2014 ban. Those are not vocabulary.
 - **It never converts a banned claim into an acceptable one.** `Revolutionary` on an owned list permits the word where the facts already support the claim it makes. It does not make the claim supportable.
 
+Before drafting, test the measured owned list against the supported propositions. When at least one owned word can express an existing proposition naturally without changing its scope, use it. Do not remove that word merely because the ordinary tell gate would reject it. An owned word is optional only when no supported sentence can carry it. Do not use owned vocabulary to manufacture a benefit, causal result, quality judgment, or product position merely to demonstrate profile adherence. Test the sentence without the owned word first; if the underlying claim is unsupported, omit the claim and accept a lower vocabulary match.
+
+For a production profile whose brief explicitly supplies measured owned vocabulary, treat that test as a required pre-draft step. If `leverage` can truthfully replace `use` in a sentence about an existing input, the word survives. If `robust` would add an unsupported quality judgment, it does not. Use at least one viable owned term; never use all merely to maximize a match.
+
+Sentence-length and paragraph-shape measurements are distributions, not quotas or stock structures. Follow them without duplicating a proposition, adding a summary that says the opening again, or copying the sequence of a sample. The structural-tell gate fails identifiable canned framing, significance tails, decorative triads, and repeated stock templates. It does not fail a draft merely because its sentence and paragraph lengths resemble the authorized profile.
+
 **Boundary:** an owned-vocabulary list assembled from a thin corpus is a licence built on noise. Below the certification floor, no allowlist is issued at all, because a word cannot be shown to recur across genres in a corpus that has one.
 
 ## Checking adherence