@maestroagora/agora 1.1.1 → 1.2.1

package/.agents/plugins/marketplace.json

@@ -1,21 +1,21 @@
-{
-  "name": "maestro-agora",
-  "interface": {
-    "displayName": "Maestro: Agora"
-  },
-  "plugins": [
-    {
-      "name": "maestro-agora",
-      "source": {
-        "source": "url",
-        "url": "https://github.com/mbanderas/maestro-agora.git",
-        "ref": "main"
-      },
-      "policy": {
-        "installation": "AVAILABLE",
-        "authentication": "ON_INSTALL"
-      },
-      "category": "Productivity"
-    }
-  ]
-}
+{
+  "name": "maestro-agora",
+  "interface": {
+    "displayName": "Maestro: Agora"
+  },
+  "plugins": [
+    {
+      "name": "maestro-agora",
+      "source": {
+        "source": "url",
+        "url": "https://github.com/mbanderas/maestro-agora.git",
+        "ref": "main"
+      },
+      "policy": {
+        "installation": "AVAILABLE",
+        "authentication": "ON_INSTALL"
+      },
+      "category": "Productivity"
+    }
+  ]
+}

package/.claude-plugin/marketplace.json

@@ -1,6 +1,6 @@
 {
   "name": "maestro-agora",
-  "description": "Self-hosted marketplace for Maestro: Agora, the truthful persuasion skill.",
+  "description": "Self-hosted marketplace for Maestro: Agora, the argument-first persuasion skill.",
   "owner": {
     "name": "Mark Laursen",
     "url": "https://github.com/mbanderas"
@@ -9,7 +9,7 @@
     {
       "name": "maestro-agora",
       "source": "./",
-      "description": "Turn verified truth into proof-bounded commercial, editorial, interface, and spoken copy for its real audience and surface."
+      "description": "Turn verified facts into consequential commercial, editorial, interface, and spoken arguments for the real decision."
     }
   ]
 }

package/.claude-plugin/plugin.json

@@ -1,8 +1,8 @@
 {
   "name": "maestro-agora",
-  "version": "1.1.1",
+  "version": "1.2.1",
   "displayName": "Maestro: Agora",
-  "description": "Use /agora for truthful buyer, investor, positioning, editorial, interface, and spoken copy that preserves proof limits.",
+  "description": "Use /agora for argument-first buyer, investor, positioning, editorial, interface, and spoken copy grounded in verified facts.",
   "author": {
     "name": "Mark Laursen",
     "url": "https://github.com/mbanderas"

package/.codex-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "maestro-agora",
-  "version": "1.1.1",
-  "description": "Maestro: Agora writes truthful commercial, editorial, interface, and spoken copy without outrunning the proof.",
+  "version": "1.2.1",
+  "description": "Maestro: Agora turns verified facts into consequential, channel-native arguments without outrunning the proof.",
   "author": {
     "name": "Mark Laursen",
     "url": "https://github.com/mbanderas"
@@ -19,8 +19,8 @@
   "skills": "./skills/",
   "interface": {
     "displayName": "Maestro: Agora",
-    "shortDescription": "Truthful arguments for buyers and investors",
-    "longDescription": "Install Maestro: Agora in Codex for a direct /agora skill that writes proof-bounded buyer, investor, positioning, editorial, interface, and spoken copy for its surface.",
+    "shortDescription": "Argument-first copy that earns belief",
+    "longDescription": "Install Maestro: Agora in Codex for a direct /agora skill that builds consequential buyer, investor, positioning, editorial, interface, and spoken arguments from verified facts.",
     "developerName": "Mark Laursen",
     "category": "Productivity",
     "capabilities": [
@@ -31,9 +31,9 @@
     "brandColor": "#7C3AED",
     "composerIcon": "./assets/icon.png",
     "defaultPrompt": [
-      "/agora sell Rewrite this page from one real buyer stake to a defensible belief and one supported action.",
-      "/agora invest Write an objective investor profile that makes the company mechanism and investment relevance clear.",
-      "/agora position Turn these verified facts into a proof-bounded company description for this surface."
+      "/agora position Turn these facts into a consequential company description. Keep investor relevance implicit.",
+      "/agora sell Build the strongest supported buyer argument for this surface, then give one useful next action.",
+      "/agora invest Build the capital case from timing, mechanism, proof, and what this round changes."
     ]
   }
 }

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 Mark Laursen
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 Mark Laursen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,173 +1,197 @@
-<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%" />
-</p>
-
-<h1 align="center">Maestro: Agora</h1>
-
-<p align="center"><strong>Verified truth, conducted into copy.</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>
-  <a href="https://www.npmjs.com/package/@maestroagora/agora"><img alt="npm version" src="https://img.shields.io/npm/v/@maestroagora/agora" /></a>
-  <a href="LICENSE"><img alt="MIT license" src="https://img.shields.io/badge/license-MIT-7c3aed" /></a>
-</p>
-
-Agora is a portable Agent Skill for truthful persuasion. It turns verified company and product truth into a supported path from a real stake to a defensible belief. The method covers buyer, investor, company-positioning, informational, and transactional copy. It never authorizes a claim the proof cannot carry.
-
-Give it the real situation, evidence, material limits, and requested surface. Agora returns ready-to-use copy first and puts any material verification need after the draft.
-
-**Related Maestro tools:**
-
-- **[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 truth into proof-bounded arguments for buyers and investors, including objective company positioning.
-- **[Maestro CostGuard](https://github.com/mbanderas/costguard):** Audits CI and cloud infrastructure for cost leaks and shows what to fix.
-
-## Install
-
-One command installs Agora for the shared Agent Skills path and Claude Code:
-
-```sh
-npx -y @maestroagora/agora
-```
-
-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.
-
-Choose a native target or project-local scope when you need one:
-
-```sh
-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
-```
-
-Supported targets are `universal`, `shared`, `codex`, `claude`, `cursor`, `gemini`, `copilot`, and `windsurf`. Add `--force` only when you intend to replace a different copy at the exact `agora` destination.
-
-### Native plugin install
-
-Claude Code:
-
-```text
-/plugin marketplace add mbanderas/maestro-agora
-/plugin install maestro-agora@maestro-agora
-```
-
-Codex CLI:
-
-```sh
-codex plugin marketplace add mbanderas/maestro-agora
-codex plugin add maestro-agora@maestro-agora
-```
-
-The npm installer is the broadest route across IDEs. The native plugin commands install the repository's matching Claude or Codex manifest.
-
-## Use Agora
-
-Invoke the skill directly, name a mode when you want one, then provide the facts it may use:
-
-```text
-/agora sell Rewrite this upgrade screen from one real buyer stake to a defensible belief. Keep one supported CTA. Use only these verified facts: ...
-```
-
-In Codex, `$agora` and the skills picker can also select the installed skill. Other hosts may expose skills through their own picker or mention syntax; asking the agent to "use the agora skill" remains portable.
-
-### Commercial modes
-
-An explicit mode wins. When no mode is named, Agora infers one from the requested asset and the audience's decision.
-
-| Mode | Use or infer it for |
-|---|---|
-| `SELL` | Marketing, sales, ads, landing pages, outreach, or paywalls |
-| `INVEST` | Investors, funding, pitches, or capital-focused profiles |
-| `POSITION` | Company profiles, category narratives, or brand descriptions |
-| `INFORM` | Editorial or educational work |
-| `TRANSACT` | Buttons, confirmations, alerts, or utility microcopy |
-
-### Surface routing
-
-Mode and surface are separate decisions. An investor description on Crunchbase is `INVEST` on an indexable public, objective profile surface. A paywall is `SELL` on a written interface surface. A published transcript is written even when its source script is spoken.
-
-| Surface | Treatment |
-|---|---|
-| `INDEXABLE_PUBLIC` | Public claim review, written human-voice and GEO/AEO gates, plus a technical publication handoff |
-| `PUBLIC_NON_INDEXABLE_WRITTEN` | Public claim review, written semantic and evidence rules, plus the human-voice gate; skip crawl and index checks |
-| `WRITTEN_PRIVATE` | Proof fidelity, concrete entities, self-contained claims, and the human-voice gate |
-| `SPOKEN_ONLY` | Proof review, cadence, breath, timing, and listener comprehension; skip GEO/AEO formatting |
-| `HYBRID` | Route every spoken and written derivative separately |
-
-### Commercial spine
-
-For `SELL`, `INVEST`, and `POSITION`, Agora constructs this exact sequence:
-
-```text
-Recognizable reality -> consequence or opportunity -> new decision criterion -> company or product mechanism -> defensible destination belief -> action or investment relevance.
-```
-
-Moves may share sentences; none may disappear.
-
-1. Recognizable reality. Name the audience's current situation without inventing pain, motive, or urgency.
-2. Consequence or opportunity. Make one truthful stake felt through a concrete business effect, decision risk, or available gain.
-3. New decision criterion. Establish what a credible choice must do, based on the supplied facts.
-4. Company or product mechanism. Explain what changes, what causes the change, and what limits apply.
-5. Defensible destination belief. Land one supported commercial conclusion.
-6. Action or investment relevance. State the logical next step, or why the company merits evaluation when the channel does not permit a CTA.
-
-### Objective-channel cap
-
-On objective platforms such as Crunchbase, the channel caps tone, not argument. Agora keeps the commercial spine factual and compact. It does not replace the stake with hype or force a sales command where investment relevance is the permitted close. If the channel conflicts with the requested commercial job, Agora returns usable copy first and names the conflict afterward.
-
-## What the skill enforces
-
-Agora chooses the commercial job before it formats the surface. Proof review happens before the later formatting and compression passes.
-
-- Preserve every load-bearing move for `SELL`, `INVEST`, and `POSITION` work before formatting the channel.
-- Keep proof beside the claim, with its source, scope, date, qualification, and material limits.
-- Use the strongest factual argument an objective channel permits instead of settling for a hollow profile.
-- Cut Wikipedia-style flagged vocabulary, connectives, templates, significance tails, generated em dashes, curly quotes, fabricated texture, and decorative recaps.
-- Narrow, omit, or flag unsupported claims instead of supplying missing features, prices, routes, urgency, scarcity, testimonials, or results.
-- Return one usable draft before assumptions, verification needs, or an objective-channel conflict.
-- Remove repetition before cutting a stake, mechanism, proof limit, destination belief, or action relevance.
-
-The skill improves process discipline; it does not replace source review, legal review, or final human verification.
-
-## Written GEO/AEO boundaries
-
-For written assets, Agora treats generative-engine optimization and answer-engine optimization as clarity and evidence work: answer the reader's question early, name entities and scope, keep proof adjacent to claims, expose provenance, and make useful passages self-contained.
-
-For indexable public pages, it can also flag technical publication checks such as crawlability, canonical consistency, structured data, and sitemap inclusion. These practices can improve eligibility and citability; they cannot promise retrieval, selection, quotation, citation, ranking, recommendation, referral, conversion, or revenue.
-
-Spoken-only delivery skips GEO/AEO formatting. Published titles, descriptions, transcripts, captions, show notes, and companion pages receive the written treatment separately.
-
-## How Agora works
-
-<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>
-
-The public skill stays intentionally small:
-
-```text
-skills/agora/
-├── SKILL.md
-├── agents/
-│   └── openai.yaml
-└── references/
-    └── agora-marketing.md
-```
-
-`SKILL.md` contains the operating workflow. `references/agora-marketing.md` is the canonical authority for evidence grades, ethical limits, persuasion controls, AI-writing-tell checks, and GEO/AEO boundaries. CiteSurge-specific rules remain isolated to CiteSurge work.
-
-## Verify the package
-
-```sh
-npm run check
-npx -y @maestroagora/agora --dry-run
-```
-
-The validation suite checks the strict skill root, the v1.1 behavior contract, plugin metadata, relative links, installer behavior, and the exact npm package allowlist. A committed blind-eval corpus covers mode and surface combinations without calling a model during CI.
-
-## License
-
-[MIT](LICENSE)
+<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%" />
+</p>
+
+<h1 align="center">Maestro: Agora</h1>
+
+<p align="center"><strong>Verified truth, conducted into copy.</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>
+  <a href="https://www.npmjs.com/package/@maestroagora/agora"><img alt="npm version" src="https://img.shields.io/npm/v/@maestroagora/agora" /></a>
+  <a href="LICENSE"><img alt="MIT license" src="https://img.shields.io/badge/license-MIT-7c3aed" /></a>
+</p>
+
+Most writing tools start with words. Agora starts with the decision behind them.
+
+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.
+
+Use Agora for landing pages, ads, company profiles, investor narratives, sales email, product copy, paywalls, editorial work, interface text, and spoken scripts.
+
+**One suite: fuse the answer, make the case, guard the spend.**
+
+- **[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.
+
+## Install
+
+Install Agora across the shared Agent Skills path and Claude Code:
+
+```sh
+npx -y @maestroagora/agora
+```
+
+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.
+
+Choose a target or project-local scope when needed:
+
+```sh
+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
+```
+
+Supported targets are `universal`, `shared`, `codex`, `claude`, `cursor`, `gemini`, `copilot`, and `windsurf`. Add `--force` only when you intend to replace a different copy at the exact `agora` destination.
+
+Update an existing user installation:
+
+```sh
+npx -y @maestroagora/agora@latest --target universal --scope user --force
+```
+
+### Native plugin install
+
+Claude Code:
+
+```text
+/plugin marketplace add mbanderas/maestro-agora
+/plugin install maestro-agora@maestro-agora
+```
+
+Codex CLI:
+
+```sh
+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.
+
+## Use Agora
+
+Invoke the skill directly and provide the facts it may 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:
+
+```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 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:
+
+```text
+situation -> stake -> criterion when useful -> mechanism -> proof -> destination belief -> next step
+```
+
+That path stays internal. It is not a paragraph template.
+
+- 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.
+
+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.
+
+### Mode routing
+
+| 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 |
+| `TRANSACT` | Buttons, confirmations, alerts, forms, and utility microcopy |
+
+`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."
+
+### Proof salience
+
+Agora ranks facts by decision relevance, differentiation, verifiability, specificity, compression value, and omission risk.
+
+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.
+
+### Emotion without invention
+
+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.
+
+It never manufactures fear, urgency, scarcity, loss, social proof, intimacy, or certainty. Emotion makes the facts consequential. It does not replace them.
+
+## Surface routing
+
+Mode and surface are separate decisions.
+
+| Surface | Treatment |
+|---|---|
+| `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 |
+
+Published titles, descriptions, transcripts, captions, show notes, and companion pages receive written treatment. Spoken-only delivery stays free of search-format scaffolding.
+
+## Silent safeguards
+
+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.
+
+- 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, generated em dashes, and smart quotes.
+- Necessary factual series survive the cleanup.
+- One ready-to-use result comes first. Near-duplicate variants appear only when requested.
+
+The skill improves writing discipline. It does not replace source review, legal review, or final human judgment.
+
+## 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 proof beside claims, exposes real provenance, and builds useful passages that remain accurate when quoted alone.
+
+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.
+
+## How Agora works
+
+<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>
+
+The skill itself stays intentionally small:
+
+```text
+skills/agora/
+├── SKILL.md
+├── agents/
+│   └── openai.yaml
+└── references/
+    └── agora-marketing.md
+```
+
+`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.
+
+## Verify the package
+
+```sh
+npm run check
+npx -y @maestroagora/agora --dry-run
+```
+
+The validation suite checks the strict three-file skill root, the v1.2 behavior contract, plugin metadata, relative links, installer behavior, source-link retention, project-agnostic content, and the exact npm package allowlist. A committed blind-eval corpus covers known failure modes without passing expected answers or grading rules into generation.
+
+## License
+
+[MIT](LICENSE)