@maestroagora/agora 1.3.0 → 1.6.0

package/README.md

@@ -1,10 +1,10 @@
 <p align="center">
-  <img src="assets/maestro-agora-banner.png" alt="The Maestro mascot writing with a gold fountain pen as evidence cards become a finished page" width="100%" />
+  <img src="assets/maestro-agora-banner.png" alt="The Maestro mascot turning rough notes into a finished page with a gold fountain pen" width="100%" />
 </p>
 
 <h1 align="center">Maestro: Agora</h1>
 
-<p align="center"><strong>Verified truth, conducted into copy.</strong></p>
+<p align="center"><strong>Say what matters. Make it land.</strong></p>
 
 <p align="center">
   <a href="https://github.com/mbanderas/maestro-agora/actions/workflows/validate.yml"><img alt="Validation status" src="https://github.com/mbanderas/maestro-agora/actions/workflows/validate.yml/badge.svg" /></a>
@@ -12,17 +12,33 @@
   <a href="LICENSE"><img alt="MIT license" src="https://img.shields.io/badge/license-MIT-7c3aed" /></a>
 </p>
 
-Words cannot rescue a missing argument. Agora starts with the decision behind the copy.
+Agora helps you turn what your business does, knows, sells, imagines, or explains into writing people can understand and act on.
 
-Give it verified facts, the real audience, and the surface where the copy will live. Agora finds the consequential shift or stake, explains the mechanism that changes it, selects the proof that matters most, and turns that case into channel-native copy. The result can feel urgent, ambitious, reassuring, or direct. It cannot outrun the evidence.
+It starts with the decision behind the copy. Who must understand, believe, choose, approve, fund, or do something next? Agora finds the consequential stake, explains why the subject matters, chooses the details that move the decision, and writes for the actual channel.
 
-Use Agora for landing pages, ads, company profiles, investor narratives, sales emails, product copy, paywalls, editorial work, interface text, and spoken scripts.
+Use it for landing pages, heroes, ads, product copy, sales outreach, investor communication, scientific and technical explanation, case studies, company profiles, editorial work, interface text, and spoken scripts. Agora follows your brief. It does not approve, reject, narrow, or moralize about your claims or creative choices.
 
-**One suite: fuse the answer, make the case, guard the spend.**
+## What Agora adds
 
-- **[Maestro Frontier](https://github.com/mbanderas/maestro):** Fuses the model CLIs you already run into one judged, grounded answer.
-- **[Maestro Agora](https://github.com/mbanderas/maestro-agora):** Turns verified product truth into concise, argument-first copy without inventing the proof.
-- **[Maestro CostGuard](https://github.com/mbanderas/costguard):** Audits CI and cloud infrastructure for cost leaks and shows what to fix.
+| Capability | What it controls |
+|---|---|
+| Persuasion | Argument, consequence, reason to believe, CTA, channel fit, and rhetorical force |
+| Heroes and short sales copy | Awareness, claim saturation, traffic source, promise grammar, destination fidelity, and the complete first-screen composition |
+| `SCIENCE` | Scientific certainty, causal language, statistics, mechanisms, uncertainty, analogies, visuals, sources, and limits |
+| `CASE_STUDY` | Real projects, fictional mocks, and concept portfolios shaped around the story and status you choose |
+| `INVEST` | Fundraising, diligence, and capital-allocation communication shaped around your thesis, claims, urgency, and next decision |
+| `VOICE` | A measured voice profile built from the corpus you choose |
+| Written GEO/AEO | Clear entities, self-contained passages, source transparency, and relevant publication checks |
+
+Agora returns one ready-to-use result by default. Alternatives, internal routes, and rationale stay out of the final copy unless requested.
+
+## When buyers ask AI, is your brand part of the answer?
+
+More decisions now start inside an AI answer. Buyers ask for comparisons, explanations, and recommendations; brands either enter that answer or they do not.
+
+[CiteSurge](https://citesurge.com/) tracks how your brand and competitors appear across ChatGPT, Claude, Perplexity, Gemini, Google AI Overviews, Bing Copilot, and Grok. Run Prompt Scans for the questions your customers may ask. Measure competitive Share of Voice. See which brands and sources shape each answer. Then turn what you find into prioritized Content Recommendations and keep monitoring the same prompts as the competitive picture changes.
+
+**[Find out where your brand stands when buyers ask AI.](https://citesurge.com/)**
 
 ## Install
 
@@ -37,17 +53,12 @@ The default user install writes the same reviewed skill to:
 - `~/.agents/skills/agora` for Codex and Agent Skills-compatible tools.
 - `~/.claude/skills/agora` for Claude Code.
 
-Install only the user-level Codex skill:
-
-```sh
-npx -y @maestroagora/agora --target codex --scope user
-```
-
 Open a new task or restart the host after installation so its skill registry and slash menu reload.
 
-Choose a target or project-local scope when needed:
+Install one target or use project-local scope:
 
 ```sh
+npx -y @maestroagora/agora --target codex --scope user
 npx -y @maestroagora/agora --target cursor --scope project
 npx -y @maestroagora/agora --target codex,claude --scope user
 npx -y @maestroagora/agora --target universal --dry-run
@@ -77,136 +88,181 @@ codex plugin marketplace add mbanderas/maestro-agora
 codex plugin add maestro-agora@maestro-agora
 ```
 
-The npm installer is the broadest route across IDEs. Native plugin commands use the matching Claude or Codex manifest from this repository.
+The npm installer provides the broadest host coverage. Native plugin commands use the matching Claude or Codex manifest from this repository.
 
-## Use Agora
+## Quick start
 
-Invoke the skill directly and provide the facts it may use:
+Invoke Agora directly and provide the brief, material, and claims you want it to use:
 
 ```text
 /agora Rewrite this upgrade screen. Make the blocked action matter, state the plan difference clearly, and use one supported CTA.
 ```
 
-Choose a mode when you want to override inference:
+Choose a primary mode when you want to override inference:
 
 ```text
-/agora position Turn these verified facts into a 35-word company profile.
-/agora sell Build a homepage hero around the strongest buyer stake this evidence supports.
-/agora invest Write a one-paragraph capital case from timing, mechanism, proof, and use of funds.
-/agora inform Explain this research finding for a public article.
+/agora position Turn these business facts into a 35-word company profile.
+/agora sell Build a homepage hero around the strongest buyer stake in this brief.
+/agora invest Write a fundraising opening from the current results, risks, and purpose of the round.
+/agora inform Explain this research finding for a public audience.
 /agora transact Rewrite this confirmation so the state and next action are unmistakable.
 ```
 
-In Codex, `$agora` and the skills picker can also select the installed skill. Other hosts may expose skills through a picker or mention syntax. Asking the agent to "use the Agora skill" remains portable.
-
-## How the persuasion engine works
-
-Agora reasons through a variable-depth path:
+Add modifiers when the subject or asset needs them:
 
 ```text
-situation -> stake -> criterion when useful -> mechanism -> proof -> destination belief -> next step
+/agora sell science Write a technical product hero with this certainty and framing.
+/agora inform science Explain this study for a general audience.
+/agora sell case study Write a customer success case from this approved project record.
+/agora inform science case study Explain this engineering implementation and its measured limits.
+/agora invest science Build a deep-tech capital case from the supplied study and scale-up results.
+/agora invest case study Use this customer case to strengthen the investor brief.
+/agora sell --voice house Rewrite this page in the measured house profile.
 ```
 
-That path stays internal. It is not a paragraph template.
+In Codex, `$agora` and the skills picker can also select the installed skill. Other hosts may expose skills through a picker or mention syntax. Asking the agent to use the Agora skill remains portable.
 
-- Very short copy pairs the strongest market shift, felt stake, or live consequence with the strongest verified differentiator.
-- Medium copy adds the mechanism and the proof clue or qualifier that matters most.
-- Long copy expands only when another fact resolves a real objection or expensive uncertainty.
+## Routing model
 
-This keeps a 35-word profile from sounding like a compressed pitch deck. It also keeps a full investor narrative from collapsing into a feature list.
+Agora chooses a primary mode first, then the publication surface, then any domain or asset modifiers. `VOICE` enters afterward and preserves your required language and content choices.
 
-### Mode routing
+### Primary modes
 
 | Mode | Use or infer it for |
 |---|---|
 | `POSITION` | Company profiles, directories, About copy, website summaries, category narratives, and objective descriptions |
 | `SELL` | Marketing, sales, ads, landing pages, product pages, outreach, upgrades, and paywalls |
-| `INVEST` | Actual funding, capital-allocation, diligence, investor-pitch, and fundraising work |
-| `INFORM` | Editorial and educational work |
+| `INVEST` | Actual funding, diligence, investor-pitch, and capital-allocation decisions |
+| `INFORM` | Editorial, educational, scientific, and technical explanation |
 | `TRANSACT` | Buttons, confirmations, alerts, forms, and utility microcopy |
-| `VOICE` | A modifier on any of the above, not a job of its own. `--voice <name>` writes in a measured author profile |
 
-`POSITION` is the default for descriptive company profiles, even when investors may read them. Agora makes relevance emerge from the shift, mechanism, wedge, and proof. It does not insert phrases such as "for investors" or "merits evaluation."
+`POSITION` remains the default for descriptive company profiles, even when investors may read them. Directory placement does not convert an objective profile into a capital pitch.
+
+### Composable modifiers
+
+| Modifier | Function |
+|---|---|
+| `SCIENCE` | Adds empirical or technical explanation and optional claim-review tools |
+| `CASE_STUDY` | Adds case-study structure, result framing, and optional attribution or permission review |
+| `VOICE` | Applies a measured voice profile from the corpus you select |
+
+The modifiers can compose. A technical fundraising case may use `INVEST + SCIENCE + CASE_STUDY`. A founder-voiced scientific product video may use `SELL + SCIENCE + VOICE + HYBRID`.
 
-### Proof salience
+### Surfaces
 
-Agora ranks facts by decision relevance, differentiation, verifiability, specificity, compression value, and omission risk.
+| Surface | Treatment |
+|---|---|
+| `INDEXABLE_PUBLIC` | Human-voice and GEO/AEO passes, then relevant technical publication checks |
+| `PUBLIC_NON_INDEXABLE_WRITTEN` | Clear written structure and human-voice pass; no crawl or index checks |
+| `WRITTEN_PRIVATE` | Channel fit, concrete meaning, and human-voice pass |
+| `SPOKEN_ONLY` | Cadence, breath, timing, and listener comprehension; no GEO/AEO formatting |
+| `HYBRID` | Spoken delivery and each written derivative are routed separately |
 
-It keeps the facts that change the decision. A measured outcome may outrank five minor features. A named list of supported engines may be the proof when scope is the decision. Diagnostic enumeration stays. Decorative feature volume goes.
+Titles, descriptions, captions, show notes, transcripts, and companion pages receive written treatment. Spoken narration stays free of search-format scaffolding.
 
-### Emotion without invention
+## How the argument works
 
-Agora chooses one dominant emotional job, such as tension, relief, control, ambition, belonging, or curiosity. It expresses that feeling through a real situation, a supportable consequence, and available agency.
+Agora reasons through a variable-depth path:
 
-It never manufactures fear, urgency, scarcity, loss, social proof, intimacy, or certainty. Emotion makes the facts consequential. It does not replace them.
+```text
+situation -> stake -> criterion when useful -> mechanism -> reason to believe -> destination belief -> next step
+```
 
-## Surface routing
+This path is not a paragraph template.
 
-Mode and surface are separate decisions.
+- Short copy pairs the strongest live consequence with the strongest supplied differentiator.
+- Medium copy adds the mechanism and the result, detail, or qualification that matters most.
+- Long copy expands only when another fact resolves a real objection or expensive uncertainty.
 
-| Surface | Treatment |
+Agora ranks supporting details by decision relevance, differentiation, specificity, compression value, and omission risk. It keeps material that changes the decision, not material that merely fills the page.
+
+## Heroes and short-form sales copy
+
+A hero is one distributed argument, not a headline contest. Agora evaluates:
+
+- Optional eyebrow.
+- Headline.
+- Subhead.
+- Primary and optional secondary CTA.
+- Result or qualification microcopy.
+- Visual, demo, or result context.
+- Immediate next section.
+
+It distinguishes brief fidelity from persuasive quality. Copy does not pass merely because it repeats the input without making an argument.
+
+`SELL` on a first-attention surface normally receives a commercially assertive treatment. Mid-funnel explanation receives a persuasive-explanatory treatment. Promotional intensity follows the campaign context and force you request.
+
+Promise grammar matters. `See X`, `Learn how to X`, `We help you X`, `Do X more often`, `You will X`, and an imperative such as `Beat X` create different expectations. CTA language must match the destination and its commitment level.
+
+## Scientific and technical communication
+
+`SCIENCE` supports three internal routes:
+
+| Route | Subject |
 |---|---|
-| `INDEXABLE_PUBLIC` | Public claim review, human-voice and GEO/AEO passes, then relevant technical publication checks |
-| `PUBLIC_NON_INDEXABLE_WRITTEN` | Public claim review, written evidence structure, and human-voice pass; no crawl or index checks |
-| `WRITTEN_PRIVATE` | Proof fidelity, channel fit, concrete meaning, and human-voice pass |
-| `SPOKEN_ONLY` | Proof review, cadence, breath, timing, and listener comprehension; no GEO/AEO formatting |
-| `HYBRID` | Spoken delivery and each written derivative are routed separately |
+| `EMPIRICAL` | Studies, experiments, observations, measurements, and findings |
+| `TECHNICAL` | Systems, interfaces, architecture, mechanisms, dependencies, and failure behavior |
+| `MIXED` | Measured findings plus technical mechanism |
 
-Published titles, descriptions, transcripts, captions, show notes, and companion pages receive written treatment. Spoken-only delivery stays free of search-format scaffolding.
+When you request scientific claim review, Agora can classify material as observation, established fact or consensus, model, interpretation, implication, recommendation, hypothesis, speculation, or unknown. Without that request, it follows the certainty and framing in your brief.
 
-## Silent safeguards
+Agora can preserve study design, population, comparator, baseline, denominator, absolute and relative effects, material uncertainty, and the difference between statistical and practical significance when your task needs that precision.
 
-Agora builds the argument before it runs publication and style checks. Those checks remain invisible unless the delivered copy would otherwise be misleading, legally unusable, or operationally unshippable.
+Misconception hooks, question-first explanation, analogies, visuals, and alternating narrative threads are optional tools. Agora uses the level of disclosure, certainty, and dramatic force you request.
 
-- Unsupported claims are narrowed or removed, not buried under a disclaimer.
-- Facts, inference, interpretation, aspiration, and promises remain distinct.
-- GEO/AEO improves written clarity and evidence structure after the argument exists.
-- Human-voice cleanup removes prompt leakage, canned templates, generic significance tails, and smart quotes. A separate hard invariant bans U+2014 from the entire generated response, including copied text and commentary, with a mandatory final character scan.
-- Necessary factual series survive the cleanup.
-- One ready-to-use result comes first. Near-duplicate variants appear only when requested.
+## Case studies built around what happened
 
-The skill improves writing discipline. It does not replace source review, legal review, or final human judgment.
+`CASE_STUDY` supports:
 
-## Written GEO/AEO boundaries
+| Family | Primary focus |
+|---|---|
+| `CUSTOMER_SUCCESS` | Buyer problem, intervention, measured result, attribution, and decision relevance |
+| `CREATIVE_PORTFOLIO` | Brief, constraints, insight, concept, role, decisions, execution, and results |
+| `TECHNICAL_IMPLEMENTATION` | System constraint, alternatives, architecture, rollout, failure modes, observed performance, and tradeoffs |
 
-For written assets, Agora answers the reader's question early when the format calls for it, names entities and scope, keeps proof beside claims, exposes real provenance, and builds useful passages that remain accurate when quoted alone.
+Case family and project status are separate:
 
-For indexable public pages, Agora can also flag relevant crawlability, canonical, sitemap, metadata, structured-data, accessibility, and delivery checks. These practices can improve eligibility and citability. They cannot promise retrieval, selection, quotation, citation, ranking, recommendation, referral, conversion, or revenue.
+| Project status | What Agora permits |
+|---|---|
+| Real project | Builds from the history, roles, artifacts, quotes, measurements, and results you provide |
+| Fictional mock | Invents a coherent case to the scope and realism you request |
+| Concept portfolio | Builds a self-initiated or speculative scenario to the framing you request |
 
-## AI visibility after publication
+You choose whether a case is real, fictional, mixed, anonymous, attributed, disclosed, or presented without a status label. Agora does not police that choice.
 
-Agora turns verified facts into argument-first copy. It does not measure whether AI answers mention your brand or cite your sources. [CiteSurge](https://CiteSurge.com) is a separate platform for citability engineering and cross-engine AI visibility tracking.
+Every result is classified before writing: measured outcome, customer-reported outcome, observed process or adoption change, supported inference, target, pending measurement, or unmeasured.
 
-## How Agora works
+Agora can separate delivery activity, business impact, chronology, and causality when you request case review. Otherwise it follows the outcome framing in your brief.
 
-<p align="center">
-  <img src="assets/agora-orbit.svg" alt="Animated flow from verified truth and evidence through argument, proof, voice, and action into ready copy" width="100%" />
-</p>
+Permission, attribution, confidentiality, quote, and disclosure review are optional. Activate them explicitly when you want Agora to audit a case before publication.
 
-The skill itself stays intentionally small:
+Academic and clinical case reports remain outside this capability.
 
-```text
-skills/agora/
-├── SKILL.md
-├── agents/
-│   └── openai.yaml
-└── references/
-    ├── agora-craft.md
-    ├── agora-marketing.md
-    └── agora-voice.md
-```
+## Investment communication
+
+`INVEST` remains one primary mode with three internal routes:
 
-`SKILL.md` is the concise operating contract. `references/agora-marketing.md` holds the original doctrine, research evidence grades, ethical limits, channel rules, AI-writing-tell controls, GEO/AEO boundaries, examples, and evaluation guidance.
+| Route | Decision |
+|---|---|
+| `FUNDRAISE` | A company seeking capital |
+| `DILIGENCE` | Testing an investment case |
+| `ALLOCATE` | Comparing or recommending capital allocation |
 
-`references/agora-craft.md` is loaded only when the task needs it. It covers four narrower domains: headlines and titles across each publishing surface, awareness and sophistication staging with its routing table, emotion written from a fact set that contains no outcome data, and prose rhythm. Every rule in it carries an evidence grade and a stated failure condition, every number is either sourced or labelled a governance default, and the two cadence conflicts the research left open are recorded rather than resolved.
+Agora can separate historical results, current state, contracted commitments, customer reports, forecasts, targets, model assumptions, interpretations, scenarios, and unknowns when you request diligence or claim review. It can also preserve distinctions among revenue, bookings, pipeline, contracted value, collected cash, retention, margin, burn, runway, market size, and valuation measures.
 
-`references/agora-voice.md` governs `VOICE`, the one mode that modifies another rather than replacing it. `--voice <name>` loads a measured author profile on top of whichever job was already selected, and `voice build`, `voice list`, and `voice check` manage the profiles themselves. A profile is measured rather than described: it records sentence and paragraph distributions, function words, punctuation, openings, and stance, states plainly what the corpus was too small to measure, and refuses certification below 5,000 clean author-controlled words.
+It can produce warm introductions, direct outreach, spoken openings, decks, briefs, demos, follow-ups, diligence memos, investment-committee briefs, data-room narratives, and progress updates. It does not impose a universal deck order, deck length, meeting script, talk ratio, outreach rule, or opening duration.
 
-Profiles are stored at `~/.agora/voices/`, deliberately outside the skill directory, because the documented update path replaces that directory and would destroy them. Voice enters at level 6 of the conflict hierarchy: it never licenses an unsupported claim, never overrides required or legal phrasing, and never overrides the em-dash ban. It carries exactly one exception, written down because the alternative is a gate that strips the voice it was loaded to keep: a profile's measured owned-vocabulary list suppresses the generic AI-vocabulary ban for those specific words only. Building or applying a third-party profile for publication under that person's name is refused.
+Strong fundraising communication makes the decision, present position, purpose of the capital, and next milestone clear. Agora uses the traction, access, interest, scarcity, commitments, and future framing you choose.
 
-### Building a voice profile
+When diligence is the task, Agora can keep a weakness visible until new results resolve it. In fundraising work, it follows the strategic framing you request.
 
-Measurement is computed by a shipped engine, not estimated by the model, because a model asked to describe an author's voice writes flattery:
+Legal, securities, offering, solicitation, eligibility, and disclosure review is optional and must be requested explicitly.
+
+## Measured voice profiles
+
+`VOICE` modifies another mode rather than replacing it. Profiles are measured from the corpus you select, not improvised from adjectives.
+
+Build and inspect a profile with the shipped engine:
 
 ```sh
 npx -p @maestroagora/agora agora-voice build --name house \
@@ -217,34 +273,106 @@ npx -p @maestroagora/agora agora-voice list
 npx -p @maestroagora/agora agora-voice check --voice house ./draft.md
 ```
 
-The engine reads Markdown, plain text, and HTML from files, directories, and URLs. It refuses binary document formats by name rather than extracting them partially, because every admission threshold counts clean author-controlled words and a partial extraction would move all of them silently. Quotations, code, tables, signatures, front matter, and headings are stripped before anything is counted, and the profile records what the cleaning removed.
+The engine reads Markdown, plain text, and HTML from files, directories, and URLs. It removes quotations, code, tables, signatures, front matter, and headings before measurement. Binary document formats are refused by name rather than partially extracted.
 
-It measures nine feature families: sentence length with percentiles and binned shape, clause structure as a labelled conjunction proxy, function words, punctuation, paragraph shape, lexical diversity by moving-window and decay-based measures, person and stance, sentence openings, and contraction rate scoped to contexts where both forms were grammatical. Raw type-token ratio is withheld by rule, since it falls mechanically as texts grow. Anything the corpus cannot support is written as insufficient data.
+A profile records sentence and paragraph distributions, function words, punctuation, openings, stance, contraction behavior, and supported vocabulary. It states what the corpus was too small to measure and refuses certification below 5,000 clean author-controlled words.
 
-Four admission gates run before a profile is certified: at least 10 independent documents with none above 25 percent of clean tokens, 2,500 clean words across 3 documents before a register earns its own numbers, a two-part feature stability rule, and a heterogeneity stop that offers two profiles rather than averaging two registers into a voice belonging to nobody. Below 5,000 clean words nothing is written at all and the tool reports what the corpus needs.
+Profiles live at `~/.agora/voices/`, outside the replaceable skill directory. A default profile can apply across modes. Use `--no-voice`, `neutral`, or `--voice <name>` per request. Your required wording overrides habitual profile tendencies.
 
-Once a default profile exists, it applies to every mode. Opt out per request with `--no-voice` or `neutral`, or name a different profile with `--voice <name>`.
+Agora builds or applies the profile you request. You are responsible for corpus rights, identity use, attribution, endorsements, disclosure, and publication.
 
-## Change record
+## User control and responsibility
 
-| Version | What changed |
-|---|---|
-| 1.3.0 | `VOICE` becomes executable. A deterministic measurement engine ships as the `agora-voice` command: a frozen tokenizer, sentence segmenter, and lexicon; ingestion and cleaning for Markdown, plain text, and HTML from files, directories, and URLs, with binary formats refused by name; nine measured feature families with withheld rather than guessed values; all four corpus admission gates; profile and registry writing under `~/.agora/voices/`; and `voice check` with draft-length bands, register matching, and a phrase-overlap index stored as hashed token runs rather than as corpus text. A default profile now applies to every mode, with `--no-voice` and `neutral` as the opt-outs. Two blind eval cases added for build-from-corpus and the owned-vocabulary-against-tell-gate conflict. Two new references. `references/agora-craft.md` covers headlines and titles per publishing surface, awareness and sophistication staging with its routing table, emotion written from a fact set that carries no outcome data, and prose rhythm. `references/agora-voice.md` adds the `VOICE` modifier: measured author profiles stored outside the skill directory, a refusal floor below 5,000 clean author-controlled words, level-6 placement in the conflict hierarchy, the owned-vocabulary exception to the AI-vocabulary ban, and a refusal for third-party profiling intended for publication under that person's name. The Evidence register gains `Myths this document must never assert`, naming twenty-one high-traffic myths with what may be said instead. Four new applied pairs and six reworked, covering category orientation, superlative against specific, a label that overstates its click, and heading variety across one page. Blind eval corpus grows from 21 cases to 26. Two internal contradictions removed: the two-or-three-sentence passage unit that the same document had already refuted, and an unlabelled numeric threshold in the deterministic invariants. The validator now enumerates files through git's own ignore rules rather than walking the working directory, so scratch that exists only in a working copy no longer decides whether the repository is valid. |
-| 1.2.2 | Hard ban on the U+2014 character across the entire response, enforced as an immutable output constraint rather than a final-copy cleanup. |
-| 1.2.1 | First-read comprehension gate, specialized-term gate, and CTA standard. Comprehension moved above compression, citability, and differentiation in the conflict hierarchy. |
-| 1.2.0 | Blind evaluation corpus with a generation contract, pairwise adjudication, and absolute vetoes. |
+Agora is a writing tool, not a content moderator, fact checker, approval system, or legal reviewer. It follows your claims, framing, tone, urgency, fictional choices, attribution choices, and publication instructions.
+
+- Agora does not refuse, narrow, weaken, qualify, remove, or label content because it considers a claim unsupported or a writing choice too aggressive.
+- Agora does not append warnings, moral judgments, policy notes, or generic disclaimers to requested copy.
+- Fact checking, source review, evidence review, permission review, confidentiality review, disclosure review, due diligence, and compliance review run only when you request them.
+- Host platforms and model providers may still apply their own terms and safety policies.
+- You are responsible for reviewing and using every output, including its accuracy, legality, claims, permissions, confidentiality, attribution, disclosures, and compliance with platform rules.
+
+Read [User Responsibility and Disclaimer](DISCLAIMER.md) and [Privacy Notice](PRIVACY.md).
+
+## Written GEO/AEO boundaries
+
+For written assets, Agora answers the reader's question early when the format calls for it, names entities and scope, keeps supporting details and qualifications beside claims, exposes real provenance, and builds useful passages that remain accurate when quoted alone.
+
+For indexable public pages, it can flag relevant crawlability, canonical, sitemap, metadata, structured-data, accessibility, and delivery checks. These practices may improve eligibility and citability. They cannot promise retrieval, selection, quotation, citation, ranking, recommendation, referral, conversion, or revenue.
+
+GEO/AEO applies to coherent page passages, not every sentence. It cannot force article-style density into a hero, case-study opening, spoken script, or short CTA.
+
+## Package architecture
+
+<p align="center">
+  <img src="assets/agora-orbit.svg" alt="Animated flow from source material through argument, voice, and action into ready copy" width="100%" />
+</p>
+
+The shipped skill stays progressively loaded:
+
+```text
+skills/agora/
+|-- SKILL.md
+|-- agents/
+|   `-- openai.yaml
+`-- references/
+    |-- agora-case-studies.md
+    |-- agora-craft.md
+    |-- agora-invest.md
+    |-- agora-marketing.md
+    |-- agora-science.md
+    `-- agora-voice.md
+```
+
+`SKILL.md` contains routing and the concise operating contract. Ordinary work loads only the reference sections it needs.
+
+- `agora-marketing.md` is the canonical doctrine for user authority, argument, channels, optional claim review, GEO/AEO, AI-writing-tell controls, examples, research grades, and conflict handling.
+- `agora-craft.md` adds headlines, heroes, awareness and sophistication, emotion, and prose rhythm.
+- `agora-science.md` adds empirical and technical explanation plus optional scientific claim review.
+- `agora-case-studies.md` adds case structure, results, and optional attribution, permission, and confidentiality review.
+- `agora-invest.md` adds fundraising, diligence, allocation, and optional claim-review procedures.
+- `agora-voice.md` adds measured voice profiles and user-controlled profile use.
+
+## Public-package hygiene
+
+Research informed Agora, but research custody is separate from distribution.
+
+The public repository and npm package must not contain raw or corrected transcripts, caption files, supplied PDFs or office documents, audio, video, private source identities, model-output scratch, research working files, local paths, or assigned secrets.
 
-Every rule added in 1.3.0 carries an evidence grade and a stated failure condition. Every numeric threshold in the references is either followed by a source link or labelled a governance default in the same sentence. Two conflicts the research left open are recorded rather than resolved.
+`npm run check` always runs a release-hygiene scan after validation, deterministic tests, and the exact package allowlist. `npm pack` and `npm publish` run the same complete release gate through `prepack` and `prepublishOnly`.
 
-## Verify the package
+The versioned `evals/blind/v1.5.0/` corpus is retained as a historical release artifact. Its 86 prompt and manifest pairs record the v1.5.0 contract and do not govern the current user-authority behavior. Current deterministic tests verify that claim, evidence, permission, disclosure, confidentiality, diligence, and compliance review remain opt-in.
+
+## Verify
 
 ```sh
 npm run check
+npm run release:check
+npm pack --dry-run --json
 npx -y @maestroagora/agora --dry-run
 ```
 
-The validation suite checks the strict three-file skill root, current behavior and release contracts, plugin metadata, relative links, installer behavior, source-link retention, project-agnostic content, line-ending parity, and the exact npm package allowlist. A committed blind-eval corpus covers known failure modes without passing expected answers or grading rules into generation.
+The release gate checks skill structure, routing contracts, user-authority boundaries, modifiers, typography, metadata, reference links, full-tree installer parity, exact npm contents, blind-corpus integrity, and public-tree hygiene.
+
+## Change record
+
+| Version | What changed |
+|---|---|
+| 1.6.0 | Expands user control across every writing mode. User-selected claims, fiction, urgency, attribution, profile use, and publication choices now control the draft. Claim, evidence, permission, disclosure, confidentiality, diligence, and compliance review are opt-in. Adds a user-responsibility disclaimer and an accurate privacy notice. |
+| 1.5.0 | Hardens `INVEST` across fundraising, diligence, and capital allocation. Adds an investment claim ledger, metric separations, asset-specific procedures, decision-led questions, objection handling, defensibility analysis, truthful urgency and commitment language, modifier composition, and current-verification boundaries. Separates real projects from fictional mock and concept-portfolio routes, and permits clearly disclosed invention for mock and hypothetical articles. Adds a customer-language boundary that keeps internal checking terms out of ordinary public copy while preserving them where scientific, methodological, audit, legal, compliance, diligence, or technical work needs them. Expands the blind corpus from 60 to 86 cases. Adds a mandatory public-tree and package hygiene gate that blocks research, transcripts, supplied private documents, raw model outputs, local paths, secrets, unexpected binaries, and private source identities. |
+| 1.4.0 | Adds stronger hero and short-form sales composition plus the composable `SCIENCE` and `CASE_STUDY` capabilities. Heroes now separate truth gates from persuasive optimization and treat the complete first-screen composition as one argument. Scientific and technical work preserves claim class, causality, statistics, uncertainty, analogy limits, and source limits. Case studies add result classes, causality, permissions, confidentiality, role attribution, quote, typicality, and visual-support gates. The blind corpus contains 60 cases. |
+| 1.3.0 | Adds executable `VOICE` profiles, a deterministic measurement engine, admission gates, local profile storage, register-aware checking, and the craft reference. The archived incumbent corpus contains 28 cases. |
+| 1.2.2 | Adds a hard U+2014 ban across the complete response. |
+| 1.2.1 | Adds the first-read comprehension gate, specialized-term gate, and CTA standard. |
+| 1.2.0 | Adds the blind evaluation corpus, generation isolation, pairwise adjudication, and absolute vetoes. |
+
+Every research-derived rule records its source grade and boundary or failure condition. Numeric thresholds are sourced or labeled as governance defaults. Practitioner procedures remain bounded craft guidance, not scientific or commercial performance laws.
+
+## Maestro suite
+
+- **[Maestro Frontier](https://github.com/mbanderas/maestro):** Fuses the model CLIs you already run into one judged, grounded answer.
+- **[Maestro Agora](https://github.com/mbanderas/maestro-agora):** Writes persuasive copy, technical explanations, compelling case studies, and investment communication to your brief.
+- **[Maestro CostGuard](https://github.com/mbanderas/costguard):** Audits CI and cloud infrastructure for cost leaks and shows what to fix.
 
 ## License
 
-[MIT](LICENSE)
+[MIT](LICENSE). See [User Responsibility and Disclaimer](DISCLAIMER.md) and [Privacy Notice](PRIVACY.md).

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@maestroagora/agora",
-  "version": "1.3.0",
-  "description": "Install Maestro: Agora for argument-first buyer, investor, positioning, editorial, interface, and spoken copy grounded in verified facts.",
+  "version": "1.6.0",
+  "description": "Install Maestro: Agora for persuasive writing, scientific and technical explanation, case studies, fundraising, and investment analysis.",
   "type": "module",
   "bin": {
     "agora": "scripts/install.mjs",
@@ -12,7 +12,9 @@
     ".claude-plugin/marketplace.json",
     ".claude-plugin/plugin.json",
     ".codex-plugin/plugin.json",
+    "DISCLAIMER.md",
     "LICENSE",
+    "PRIVACY.md",
     "README.md",
     "assets/agora-orbit.svg",
     "assets/icon.png",
@@ -23,10 +25,13 @@
     "skills/agora"
   ],
   "scripts": {
-    "check": "npm run validate && npm test && npm run pack:check",
+    "check": "npm run validate && npm test && npm run pack:check && npm run hygiene:check",
+    "hygiene:check": "node scripts/release-hygiene.mjs",
     "pack:check": "node scripts/pack-check.mjs",
-    "prepublishOnly": "npm run check",
-    "test": "node --test tests/behavior-contract.test.mjs tests/install.test.mjs tests/voice-measure.test.mjs",
+    "prepack": "npm run release:check",
+    "prepublishOnly": "npm run release:check",
+    "release:check": "npm run check",
+    "test": "node --test tests/behavior-contract.test.mjs tests/hero-contract.test.mjs tests/science-contract.test.mjs tests/case-study-contract.test.mjs tests/invest-contract.test.mjs tests/blind-summary.test.mjs tests/release-hygiene.test.mjs tests/install.test.mjs tests/voice-measure.test.mjs",
     "validate": "node scripts/validate.mjs"
   },
   "engines": {
@@ -50,6 +55,12 @@
     "maestro",
     "marketing",
     "copywriting",
+    "science-communication",
+    "technical-writing",
+    "case-studies",
+    "fundraising",
+    "investor-communications",
+    "pitch-decks",
     "codex",
     "claude-code",
     "cursor",

package/scripts/install.mjs

@@ -247,7 +247,12 @@ async function verifySource() {
   const required = [
     "SKILL.md",
     "agents/openai.yaml",
+    "references/agora-case-studies.md",
+    "references/agora-craft.md",
+    "references/agora-invest.md",
     "references/agora-marketing.md",
+    "references/agora-science.md",
+    "references/agora-voice.md",
   ];
   for (const file of required) {
     if (!(await exists(join(SOURCE_DIR, file)))) {

package/scripts/voice/profile.mjs

@@ -444,7 +444,7 @@ export function renderProfile({ name, measured, gates, corpus, pipeline, now })
   const excerpts = selectExcerpts(corpus.documents, measured);
 
   const vocabulary = [
-    "**Owned.** Words measured as recurring across independent documents in this corpus. The list is an allowlist against the generic AI-vocabulary ban and reaches those words 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, and it never converts a banned claim into an acceptable one.",
+    "**Owned.** Words measured as recurring across independent documents in this corpus. The list is an allowlist against the generic AI-vocabulary ban and reaches those words 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.",
     "",
   ];
   if (owned.withheld) {
@@ -494,7 +494,7 @@ export function renderProfile({ name, measured, gates, corpus, pipeline, now })
     "",
     `# Voice profile: ${name}`,
     "",
-    "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 and the approved sources, never from this file.",
+    "A profile controls how a proposition is expressed. Claims, numbers, quotations, positions, preferences, endorsements, attribution, and publication decisions come from the user's current brief, not from this file.",
     "",
     "Voice enters at level 6 of the conflict hierarchy and never rises above it.",
     "",