@maestroagora/agora 1.7.0 → 1.9.0

package/.claude-plugin/marketplace.json

@@ -1,6 +1,6 @@
 {
   "name": "maestro-agora",
-  "description": "Self-hosted marketplace for Maestro: Agora, the argument-first persuasion, technical explanation, case-study, and investment-writing skill.",
+  "description": "Self-hosted marketplace for Maestro: Agora, the argument-first writing and publication artifact review skill.",
   "owner": {
     "name": "Mark Laursen",
     "url": "https://github.com/mbanderas"
@@ -9,7 +9,7 @@
     {
       "name": "maestro-agora",
       "source": "./",
-      "description": "Write user-directed commercial, technical, case-study, investment, interface, and spoken arguments that preserve the user's claims, framing, and creative choices."
+      "description": "Write user-directed commercial, technical, case-study, investment, interface, and spoken arguments, then inspect local publication artifacts when explicitly requested."
     }
   ]
 }

package/.claude-plugin/plugin.json

@@ -1,8 +1,8 @@
 {
   "name": "maestro-agora",
-  "version": "1.7.0",
+  "version": "1.9.0",
   "displayName": "Maestro: Agora",
-  "description": "Use /agora for persuasive writing, technical explanation, compelling case studies, fundraising, investment analysis, and spoken or written copy.",
+  "description": "Use /agora for persuasive writing, technical explanation, case studies, investment analysis, spoken or written copy, and explicit publication artifact audits.",
   "author": {
     "name": "Mark Laursen",
     "url": "https://github.com/mbanderas"

package/.codex-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "maestro-agora",
-  "version": "1.7.0",
-  "description": "Maestro: Agora writes clear persuasion, technical explanations, compelling case studies, and investment communication to the user's brief.",
+  "version": "1.9.0",
+  "description": "Maestro: Agora writes clear persuasion, technical explanations, case studies, and investment communication, then audits local publication artifacts when requested.",
   "author": {
     "name": "Mark Laursen",
     "url": "https://github.com/mbanderas"
@@ -25,8 +25,8 @@
   "skills": "./skills/",
   "interface": {
     "displayName": "Maestro: Agora",
-    "shortDescription": "Persuasion, science, cases, and capital",
-    "longDescription": "Install Maestro: Agora in Codex for a direct /agora skill that follows the user's claims, framing, creative choices, and intended action across commercial arguments, technical explanations, case studies, and investment communication.",
+    "shortDescription": "Writing and publication artifact review",
+    "longDescription": "Install Maestro: Agora in Codex for a direct /agora skill that follows the user's claims, framing, creative choices, and intended action across commercial arguments, technical explanations, case studies, and investment communication, with explicit read-only privacy and provenance audits for local publication artifacts.",
     "developerName": "Mark Laursen",
     "category": "Productivity",
     "capabilities": [
@@ -40,7 +40,8 @@
       "/agora sell Write the strongest hero from this brief and destination.",
       "/agora science Explain this technical subject with the certainty and framing I specify.",
       "/agora case study Turn this project material into the case study I describe.",
-      "/agora invest Build this fundraising asset from my thesis, claims, urgency, and plan."
+      "/agora invest Build this fundraising asset from my thesis, claims, urgency, and plan.",
+      "/agora publication audit Inspect this local file for hidden Unicode, metadata, and provenance."
     ]
   }
 }

package/DISCLAIMER.md

@@ -1,6 +1,6 @@
 # User Responsibility and Disclaimer
 
-Last updated: August 10, 2026
+Last updated: August 12, 2026
 
 ## Purpose
 
@@ -23,6 +23,8 @@ That responsibility includes:
 
 Agora can perform claim, evidence, permission, confidentiality, disclosure, diligence, or compliance review when explicitly requested. Such review is automated assistance, not professional advice or a guarantee that content is accurate, lawful, complete, effective, or suitable for a particular purpose.
 
+Agora can also inspect selected local publication artifacts for configured privacy, metadata, hidden-text, review-data, and provenance signals. That inspection is partial and format-dependent. It is not a watermark remover, AI detector, authorship determination, forensic examination, anonymization service, or guarantee that a file is clean, safe, private, authentic, human-written, or free of undisclosed provenance. `NOT_FOUND_BY_THIS_CHECK` applies only to the named check. `UNKNOWN` coverage remains unresolved.
+
 ## No monitoring or approval duty
 
 The project maintainer does not review, approve, monitor, or control what users ask Agora to produce or how users use its output. Availability of a feature or generated result does not constitute approval, endorsement, verification, or legal clearance.

package/PRIVACY.md

@@ -1,6 +1,6 @@
 # Privacy Notice
 
-Last updated: August 10, 2026
+Last updated: August 12, 2026
 
 ## Scope
 
@@ -35,6 +35,16 @@ These files can contain sensitive or identifiable writing. Users control the cor
 
 When a user supplies an HTTP or HTTPS URL as a corpus source, the voice tool fetches that URL from the user's computer. The remote website may receive ordinary request and network information under its own privacy policy. The fetched content and resulting profile are not sent to the Agora maintainer by the tool.
 
+## Publication audit
+
+The optional `agora-publication-audit` tool reads local files selected by the user. It computes file hashes and can inspect configured text controls, document properties, comments, notes, tracked changes, image metadata containers, and provenance signals. It does not send source files or audit reports to the Agora maintainer.
+
+The tool does not change source files. It reads each source again after inspection and reports whether its SHA-256 hash stayed unchanged. A report is written to disk only when the user supplies `--output`; the tool refuses to overwrite an existing report.
+
+Audit reports redact metadata values and absolute paths by default. `--show-values` and `--include-paths` can place sensitive or identifying information in terminal output, logs, copied reports, host prompts, or files selected by the user. Users control those options and the storage, sharing, retention, and deletion of reports.
+
+ExifTool, when already installed, runs locally in read mode to add metadata coverage. C2PA verification runs only when the user supplies `--verify-c2pa`; Agora supplies a local settings file that disables remote-manifest fetching. ExifTool, c2patool, the operating system, terminal, host application, and any separately configured wrappers remain third-party software outside the Agora project's control.
+
 ## GitHub interactions
 
 GitHub processes information when users visit the repository, download releases, open issues, create pull requests, or otherwise use GitHub. GitHub's [General Privacy Statement](https://docs.github.com/en/site-policy/privacy-policies/github-general-privacy-statement) applies to that processing.
@@ -45,7 +55,7 @@ The maintainer may receive and use information a person voluntarily submits thro
 
 Agora does not maintain a project-operated server containing user prompts, drafts, outputs, or voice profiles.
 
-Users can delete locally stored Agora files and voice profiles using their operating system. Data held by npm, GitHub, a host application, a model provider, a remote website, or another third party is governed by that third party's retention and deletion process.
+Users can delete locally stored Agora files, voice profiles, and saved audit reports using their operating system. Data held by npm, GitHub, a host application, a model provider, a remote website, or another third party is governed by that third party's retention and deletion process.
 
 ## Changes and contact
 

package/README.md

@@ -122,6 +122,31 @@ Add modifiers when the subject or asset needs them:
 
 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.
 
+## Publication privacy and provenance
+
+Agora writes copy. It does not create SVG, PNG, JPEG, PDF, DOCX, or PPTX files by itself. Other document, presentation, PDF, site, design, or image tools may place Agora copy into those artifacts.
+
+When you explicitly request a publication audit, Agora can inspect the local artifact before it leaves your control:
+
+```text
+/agora publication audit Inspect ./launch-deck.pptx before I share it.
+```
+
+Run the packaged read-only inspector directly when you want a deterministic report:
+
+```sh
+npx -y -p @maestroagora/agora@latest agora-publication-audit ./launch-deck.pptx
+npx -y -p @maestroagora/agora@latest agora-publication-audit ./public-assets --json --output audit.json
+```
+
+The inspector covers configured hidden or control characters in text, selected HTML and SVG metadata, Office properties and review material, PDF metadata, PNG and JPEG metadata containers, and C2PA carrier hints. ExifTool adds broader read-only PDF and image metadata coverage when it is already installed. `c2patool` verification is opt-in through `--verify-c2pa`, with remote-manifest fetching disabled by supplied settings.
+
+Source files are read only and compared by SHA-256 before and after inspection. Sensitive values and absolute paths are redacted by default. Missing or partial coverage is reported as `UNKNOWN`.
+
+This is publication hygiene, not a watermark remover or authorship detector. A result cannot prove that content is AI-generated, human-written, anonymous, clean, or safe. Claude's documented model-level text marking is not equivalent to unusual Unicode or ordinary file metadata.
+
+Model-level text watermarks are statistical generation signals, not hidden characters or metadata fields. Without the matching provider verifier or detector configuration and enough eligible text, Agora reports that question as uninspected instead of guessing from style, Unicode, or generic detector scores.
+
 ## Routing model
 
 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.
@@ -314,11 +339,15 @@ skills/agora/
 |-- SKILL.md
 |-- agents/
 |   `-- openai.yaml
+|-- scripts/
+|   `-- publication-audit.mjs
 `-- references/
     |-- agora-case-studies.md
+    |-- agora-conversion.md
     |-- agora-craft.md
     |-- agora-invest.md
     |-- agora-marketing.md
+    |-- agora-publication.md
     |-- agora-science.md
     `-- agora-voice.md
 ```
@@ -331,7 +360,9 @@ skills/agora/
 - `agora-case-studies.md` adds case structure, results, and optional attribution, permission, and confidentiality review.
 - `agora-conversion.md` adds bounded conversion priors, outcome matching, self-serve and enterprise route design, pricing decision contracts, decision-adjacent proof, contradiction handling, and experiment interpretation for funnel surfaces.
 - `agora-invest.md` adds fundraising, diligence, allocation, and optional claim-review procedures.
+- `agora-publication.md` adds explicit read-only publication privacy and provenance review for local artifacts.
 - `agora-voice.md` adds measured voice profiles and user-controlled profile use.
+- `publication-audit.mjs` produces a deterministic, source-preserving inspection report without a cleaning operation.
 
 ## Public-package hygiene
 
@@ -339,7 +370,9 @@ 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.
 
-`npm run check` runs validation, deterministic tests, the exact package allowlist, and release hygiene. `npm run release:check` repeats that complete distributable validation. `npm pack` and `npm publish` run it through `prepack` and `prepublishOnly`.
+`npm run check` runs validation, deterministic tests, the exact package allowlist, and release hygiene. `npm run release:check` is the proportional mandatory release gate and runs those same checks. `npm pack` and `npm publish` invoke it through `prepack` and `prepublishOnly`.
+
+Behavioral evaluation is optional research, not a pack or publish blocker. `npm run eval:release` preserves the version-specific v1.7 evidence audit and must be run from a matching v1.7 checkout. Existing evaluation artifacts remain frozen for reproducibility; new blind or confirmatory generations are not required for later releases.
 
 The versioned directories under `evals/blind/` are public pairwise-release artifacts, not permanently secret holdouts. `v1.2.0`, `v1.4.0`, `v1.5.0`, and `v1.7.0` are frozen by exact tree hashes in `evals/releases/locks.json`; validation fails on additions, deletions, or edits.
 
@@ -357,12 +390,14 @@ npm pack --dry-run --json
 npx -y @maestroagora/agora --dry-run
 ```
 
-The release gate checks skill structure, routing contracts, user-authority boundaries, modifiers, typography, metadata, reference links, full-tree installer parity, exact npm contents, frozen evaluation-tree locks, and public-tree hygiene.
+The mandatory release gate checks skill structure, routing contracts, user-authority boundaries, modifiers, typography, metadata, reference links, full-tree installer parity, exact npm contents, frozen evaluation-tree locks, public-tree hygiene, and deterministic tests. It does not require model generation or blind adjudication.
 
 ## Change record
 
 | Version | What changed |
 |---|---|
+| 1.9.0 | Makes first-read clarity automatic. Agora now drafts for factual completeness, rewrites for literal clarity, preserves qualifiers across short passages, names concrete actors and observable results, and rejects vague referents, hidden metaphors, noun stacks, and revisions that only rename ambiguity. Adds rendered label-clearance guidance for technical diagrams. |
+| 1.8.0 | Adds opt-in publication privacy and provenance review plus a packaged read-only audit CLI. Reports configured hidden Unicode, document and image metadata, Office review material, and C2PA carrier or validation signals without changing source files. Redacts sensitive values and paths by default, preserves unknown coverage, and makes no watermark-removal or authorship claim. |
 | 1.7.0 | Adds a progressively loaded conversion-context reference with bounded conversion priors, downstream outcome matching, self-serve and enterprise route design, pricing decision contracts, proof placement, and contradiction handling. Tightens closed-world fact preservation and limits written GEO/AEO requirements to indexable public work. |
 | 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. |

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "@maestroagora/agora",
-  "version": "1.7.0",
-  "description": "Install Maestro: Agora for persuasive writing, scientific and technical explanation, case studies, fundraising, and investment analysis.",
+  "version": "1.9.0",
+  "description": "Install Maestro: Agora for persuasive writing, technical explanation, case studies, investment communication, and publication artifact review.",
   "type": "module",
   "bin": {
     "agora": "scripts/install.mjs",
+    "agora-publication-audit": "skills/agora/scripts/publication-audit.mjs",
     "agora-voice": "scripts/voice-measure.mjs"
   },
   "files": [
@@ -32,7 +33,7 @@
     "prepublishOnly": "npm run release:check",
     "eval:release": "node scripts/release-evidence-check.mjs",
     "release:check": "npm run check",
-    "test": "node --test tests/behavior-contract.test.mjs tests/hero-contract.test.mjs tests/conversion-context-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/blind-judge-prompt.test.mjs tests/blind-judge-materialize.test.mjs tests/blind-judgment-ingest.test.mjs tests/adjudication-reducer.test.mjs tests/eval-provenance-check.test.mjs tests/release-evidence-check.test.mjs tests/release-hygiene.test.mjs tests/install.test.mjs tests/voice-measure.test.mjs",
+    "test": "node --test tests/behavior-contract.test.mjs tests/hero-contract.test.mjs tests/conversion-context-contract.test.mjs tests/science-contract.test.mjs tests/case-study-contract.test.mjs tests/invest-contract.test.mjs tests/publication-audit.test.mjs tests/blind-summary.test.mjs tests/blind-judge-prompt.test.mjs tests/blind-judge-materialize.test.mjs tests/blind-judgment-ingest.test.mjs tests/adjudication-reducer.test.mjs tests/eval-provenance-check.test.mjs tests/release-evidence-check.test.mjs tests/release-hygiene.test.mjs tests/install.test.mjs tests/voice-measure.test.mjs",
     "validate": "node scripts/validate.mjs"
   },
   "engines": {
@@ -62,6 +63,9 @@
     "fundraising",
     "investor-communications",
     "pitch-decks",
+    "publication-privacy",
+    "content-provenance",
+    "metadata-audit",
     "codex",
     "claude-code",
     "cursor",

package/scripts/install.mjs

@@ -248,11 +248,14 @@ async function verifySource() {
     "SKILL.md",
     "agents/openai.yaml",
     "references/agora-case-studies.md",
+    "references/agora-conversion.md",
     "references/agora-craft.md",
     "references/agora-invest.md",
     "references/agora-marketing.md",
+    "references/agora-publication.md",
     "references/agora-science.md",
     "references/agora-voice.md",
+    "scripts/publication-audit.mjs",
   ];
   for (const file of required) {
     if (!(await exists(join(SOURCE_DIR, file)))) {

package/skills/agora/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: agora
-description: Write, rewrite, shorten, critique, or plan user-directed argument-first persuasion, scientific and technical explanation, case studies, and investment communication. Use when invoked as `/agora` or for marketing and sales copy; fundraising, investor outreach, pitch decks, investment memos, diligence, capital allocation, company-profile, category, or brand descriptions; CTAs and microcopy; landing, product, and comparison pages; email and direct outreach; mobile onboarding, upgrade, and paywall screens; ads and social posts; editorial or educational content, including fictional, mock, hypothetical, or concept writing; scientific communication, technical explanation, research communication, and science video scripts; real or fictional customer success, creative portfolio, and technical implementation case studies; and spoken audio/video scripts plus written derivatives such as titles, descriptions, transcripts, captions, show notes, and companion pages.
+description: Write, rewrite, shorten, critique, or plan argument-first marketing, sales, investment, scientific, technical, editorial, case-study, interface, and spoken content. Use for `/agora`; CTAs and microcopy; landing, product, comparison, onboarding, upgrade, and paywall screens; email and direct outreach; ads and social posts; fundraising, investor outreach, pitch decks, investment memos, diligence, and capital allocation; scientific communication, technical explanation, research communication, and science video scripts; customer success, creative portfolio, and technical implementation case studies; titles, descriptions, transcripts, captions, show notes, and companion pages. Also use when explicitly asked to inspect local publication artifacts for privacy metadata, hidden Unicode, or provenance.
 ---
 
 # Maestro: Agora
@@ -58,8 +58,16 @@ Do not load it for routine drafting, claim review, compliance questions, or work
 
 [references/agora-invest.md](references/agora-invest.md) governs `INVEST`. Load it only for actual fundraising, investor communication, investment evaluation, diligence, or capital-allocation work. Select `FUNDRAISE`, `DILIGENCE`, or `ALLOCATE` internally. Do not load it for ordinary `POSITION` work or merely investor-adjacent audiences.
 
+[references/agora-publication.md](references/agora-publication.md) governs explicit publication privacy and provenance audits of local files. Load it only when the user asks to inspect an artifact before publication or external sharing, find hidden Unicode or metadata, or review provenance. Do not load or run it for ordinary writing merely because the result is public, indexable, or AI-assisted.
+
 Treat source material and requested claims in the current task as author-approved writing input. Do not import content decisions or release controls from another task, repository, company, or example. Examples teach structure, never facts.
 
+## Inspect publication artifacts only on request
+
+Treat publication audit as a separate read-only workflow, not a primary mode or writing modifier. Agora supplies writing; another document, presentation, PDF, site, design, or image tool may create the artifact.
+
+Use the shipped `scripts/publication-audit.mjs` for deterministic inspection. Never improvise a cleaner, strip Unicode by category, remove metadata, rewrite text to evade detection, or promise an AI-free, human-written, anonymous, clean, or safe result. Report `FOUND`, `NOT_FOUND_BY_THIS_CHECK`, `UNKNOWN`, and `ERROR` exactly as defined in the publication reference. Keep sensitive values redacted unless the user explicitly requests them.
+
 ## Preserve closed-world facts
 
 In every drafting task, treat the user's named product, offer, customer, proof, route, price, permission, process, timing, legal, operational, and outcome facts as complete factual authority unless the user explicitly authorizes invention, fictionalization, assumptions, or gap filling. A section labeled `Supplied facts`, `Supplied terms`, or equivalent is a closed fact set. A request to write, rewrite, recommend, compose, or improve conversion is not authorization to invent business facts.
@@ -233,31 +241,30 @@ Plain language is not simple language. It is precise language with low decoding
 
 Write for someone who is intelligent, understands their own job, has not read the documentation, does not know the organization's internal vocabulary, will not stop to decode a sentence, and is deciding whether the next line deserves attention. Familiarity with an industry is not familiarity with one organization's terms.
 
-### Test every customer-facing sentence
+### Draft twice and return once
 
-Rewrite any sentence an intended reader could not restate after reading it once. A sentence fails when it:
+Draft the factually complete argument first. Then rewrite the whole draft for literal clarity before any style, compression, voice, or publication pass. Compare the rewrite with the factual draft so every supplied fact, qualifier, relationship, and requested claim survives. Return only the rewrite.
 
-- depends on undefined internal terminology;
-- introduces more than one unfamiliar concept at a time;
-- hides the actor, the action, the object, or the result;
-- uses an abstract noun where a concrete verb would be clearer;
-- describes an internal method instead of what the reader needs to know;
-- compresses several reasoning steps into insider shorthand;
-- sounds like a specification, a compliance memo, or an academic method section when the surface does not call for that register;
-- is technically correct and practically unclear;
-- needs a different paragraph to become understandable;
-- sounds impressive before it communicates anything concrete.
+Do not treat this as optional polish. The first draft may preserve the facts and still fail because it speaks in internal categories. The second pass must change how the reader receives the meaning, not replace a few flagged words.
 
-### Gate specialized terms
+### Run the literal clarity rewrite
 
-Accuracy alone does not license an internal product, operational, analytical, or methodological term. Before using one, confirm all four:
+Rewrite any sentence an intended reader could not restate after reading it once. For every sentence that carries a mechanism, consequence, qualification, or decision, recover:
 
-1. The intended audience already knows it.
-2. It is necessary for accuracy.
-3. Its meaning is clear from the sentence it appears in.
-4. An everyday expression would lose material meaning.
+1. The concrete actor, product, component, person, or source.
+2. The finite action.
+3. The concrete object affected.
+4. The observable result, condition, or change when the claim depends on one.
 
-If any answer is no, replace the term or define it in place. Every term the reader does not already own is either decision-required and taught where it appears, or removed. Treat a sentence carrying two or more reader-unowned terms as a review trigger and not as an automatic error, and treat that count as a governance default rather than a measured limit.
+Apply these checks during the rewrite:
+
+- **Generic referent:** Treat words such as `interface`, `surface`, `system`, `asset`, `signal`, `representation`, `direction`, `property`, `origin`, and `continuity` as review triggers, not banned words. When the reader could reasonably ask which thing the word names, replace it with the concrete referent or identify that referent in the same sentence.
+- **Observable result:** State what a person could see happen. Prefer a named product listing an item, a crawler requesting a page, or a source failing to support a claim over an internal category describing the event.
+- **Specialized term:** Keep a term only when the audience owns it, accuracy requires it, its meaning is clear where it appears, and familiar words would lose material meaning. Otherwise define or remove it. Every term the reader does not own is decision-required and taught in place, or removed.
+- **Metaphor recovery:** If a metaphor carries the mechanism, test, or consequence, replace it with the literal action or result. Keep a metaphor only when the sentence remains clear without decoding it.
+- **Qualification distribution:** Keep every material scope, date, sample, product, market, method, condition, and uncertainty. Distribute them across the shortest clear passage instead of loading them into one sentence.
+- **Noun stack:** When several abstract nouns hide how things relate, convert each needed distinction into an actor and action. Abstract nouns are not banned and must not be counted.
+- **Revision integrity:** Reject a rewrite that swaps one vague noun for another, adds explanatory parentheses, or leaves the reader to recover the same missing relationship. The revised passage must make the actor, action, object, and observable result easier to identify while preserving the facts.
 
 Treat a noun the organization coined as a term the reader has no reason to know. Naming an internal method, stage, score, record type, or framework in customer-facing copy requires the reader to gain something from learning it. Otherwise state what happens and drop the name.
 
@@ -269,24 +276,6 @@ Name the concrete result, finding, number, quote, source, report, study, test, p
 
 Do not narrate internal source review in customer-facing copy unless the user asks for it. Do not narrow or omit a user-selected claim merely because Agora would prefer more support.
 
-### Prefer actor, action, object, result
-
-Answer these before drafting a sentence: who or what acts, what it does, what it acts on, and what changes for the reader.
-
-Choose the highest-frequency verb the reader already owns that preserves the factual relation and tells them what the action does. Verbs such as check, compare, find, show, verify, measure, review, choose, send, create, remove, correct, approve, reject, schedule, and calculate are a useful house lexicon, not a required set. A specialized verb wins whenever it names the exact action and the reader owns that word.
-
-Rewrite noun-heavy constructions into direct actions. Abstract nouns are not banned and must not be counted. Rewrite an abstraction when it conceals an actor, action, causal relation, or consequence the reader needs, and leave it when it carries cohesion or names an established concept. The check on each abstract noun is whether a specific actor, a finite action, and the object or result can still be recovered, and whether the reader needs them.
-
-Weak:
-
-> Evaluate whether configured operational surfaces produced compliant outcomes for the declared workflow scope.
-
-Strong:
-
-> Check whether each system finished the task you assigned it.
-
-The strong version is longer in words and shorter in effort. That trade is correct.
-
 ### Reject slogans that survive only on tone
 
 For every headline, subheading, closing line, and call to action, ask what it means literally, what action or condition it names, whether it stays useful once the dramatic tone is removed, whether twenty unrelated companies could publish it unchanged, and whether the reader learns anything or only receives a mood. If the literal meaning is thin, rewrite it.
@@ -379,7 +368,7 @@ After the argument is drafted:
 1. Honor the user's requested claims, framing, tone, and content decisions without adding policy commentary.
 2. For every draft, build a private fact ledger covering the complete response, including headings, labels, fill-in tokens, parentheticals, confirmations, conditional text, and rationale. Match every externally verifiable proposition to an explicit supplied fact, a necessary entailment, or explicit user authorization to invent. Delete or rewrite anything unmatched. When the brief is closed-world, apply the same test to every factual proposition. Plausibility, convention, usefulness, and likely implementation do not count as entailment.
 3. Run claim, evidence, permission, disclosure, or compliance checks only when the user requested that review.
-4. Run the first-read comprehension gate, the delivery-model ownership gate, the rewrite regression gate when rewriting supplied copy, the specialized-term gate, and the CTA gate. These run before any style, compression, or publication pass, and their result outranks all three.
+4. Draft twice and return once. Run the literal clarity rewrite, delivery-model ownership gate, rewrite regression gate when rewriting supplied copy, and CTA gate. These run before any style, compression, voice, or publication pass, and their result outranks all five.
 5. Apply written GEO/AEO only to `INDEXABLE_PUBLIC` work, at passage level rather than sentence level.
 6. Apply technical publication checks only to indexable public work.
 7. Apply the human-voice and AI-writing-tell gate without deleting user-selected claims or diagnostic lists.
@@ -391,7 +380,7 @@ After the argument is drafted:
 13. Make every requested component visibly distinguishable through hierarchy, spacing, or channel-native structure. The worksheet-label ban applies inside ready-to-use copy. Labels remain available outside the copy when the user requests labeled fields, when implementation recommendations need them, or when they are necessary to distinguish requested components.
 14. For conversion compositions, load and apply the surface-specific route, pricing, experiment, proof, and placement contracts in the conversion reference. Verify that visible copy follows any returned placement order, every material qualifier stays attached to the fact it qualifies, conditional steps remain conditional, unknown destinations remain unknown, and proof keeps its supplied form and causal status. Trace the primary-action spine across the flow. Do not let a prerequisite replace the activation event, make an optional post-event action primary, or invent a destination after an unknown transition. Audit every parallel option's primary decision unit for its supported route type, exclusivity, material commitment, and action or destination; an FAQ may reinforce this distinction but cannot supply it first. Audit every checklist or readiness item for a distinct fact-grounded verification, dependency, consequence, or preparation action rather than a generic instruction to review or confirm prior copy. When collection, access, or start order is absent, keep the known terms separate and do not connect them with `after`, `before`, `then`, or `until`. Scale experiment-plan detail to the requested depth without removing the minimum controls needed to interpret the named business outcome. Treat route, term, proof, and qualification completeness as the safety floor; after that floor passes, preserve the strongest supported reader job, task, or operational decision as the argument.
 
-When a sentence fails the comprehension gate, keep the underlying fact, name the concrete actor, action, object, and result, remove internal process language the reader does not need, split the overloaded sentence, restore any context the compression removed, rewrite the call to action to name its real destination, then test again. Do not repair unclear writing by adding explanatory parentheses, longer noun phrases, or a vague supporting sentence.
+When a sentence fails the comprehension gate, rewrite the full sentence or short passage through the literal clarity procedure, compare it with the factual draft, then test it again. Do not patch isolated trigger words or repair unclear writing with explanatory parentheses, longer noun phrases, or a vague supporting sentence.
 
 Keep these passes invisible. Mention a blocker only when a host rule or missing requirement makes the requested result impossible.
 

package/skills/agora/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "Maestro: Agora"
-  short_description: "Persuasion, science, cases, and capital"
-  default_prompt: "Use $agora to write clear persuasion, technical explanations, compelling case studies, and investment communication from my brief and content choices."
+  short_description: "Writing and publication artifact review"
+  default_prompt: "Use $agora to write from my brief or inspect a local publication artifact for privacy metadata and provenance."

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

@@ -334,6 +334,29 @@ A sentence fails when it:
 
 The last item is the hardest to catch from inside the draft, because impressive and clear feel similar to an author who already knows the answer. Use the literal-meaning test in `Required comprehension tests` on any sentence that felt satisfying to write.
 
+### The literal clarity rewrite
+
+Draft twice and return once. Build the factually complete argument first. Then rewrite the entire draft for literal clarity before style, compression, voice, GEO/AEO, or publication work. Compare the rewrite with the factual draft so every supplied fact, qualifier, relationship, and requested claim survives. Return only the rewrite.
+
+This is a passage rewrite, not a word-substitution pass. Run it on every sentence that carries a mechanism, consequence, qualification, or decision:
+
+1. Name the concrete actor, product, component, person, or source.
+2. Use a finite action the reader owns when it preserves the meaning.
+3. Name the concrete object affected.
+4. State the observable result, condition, or change when the claim depends on one.
+
+**Generic-referent gate.** Words such as `interface`, `surface`, `system`, `asset`, `signal`, `representation`, `direction`, `property`, `origin`, and `continuity` are review triggers, not banned words. Keep one when its concrete referent is unmistakable and the word adds meaning. When the reader could reasonably ask which interface, surface, system, asset, signal, representation, direction, property, origin, or continuity the sentence means, name the concrete thing in that sentence.
+
+**Observable-result gate.** Ask what a person could see happen. `The answer listed the product` exposes an event. `The footprint entered an answer surface` hides it inside two categories. For technical or empirical prose, distinguish what happened, how it was observed, and what it may imply. Do not replace the observed event with the method used to classify it.
+
+**Metaphor-recovery gate.** A metaphor may add emphasis after the mechanism is clear. It may not carry the only statement of the mechanism, test, or consequence. If the reader has to translate `carry the trust burden`, `flatten into one voice`, or `the asset breaks` before understanding the point, state the literal check, presentation effect, or failure instead. Keep a metaphor only when removing it leaves the sentence's factual relation intact and obvious.
+
+**Qualification-distribution gate.** Preserve material source, sample, date, product, market, method, condition, and uncertainty at passage level. Give the observed result its own sentence when possible, then place its scope and limit in adjacent sentences. Do not make one sentence independently quotable by forcing every qualifier into it.
+
+**Noun-stack gate.** When several unfamiliar abstract nouns appear together, recover each relationship the reader needs as an actor and action. Do not apply a fixed noun limit. Keep an established concept when it creates useful cohesion or precision; rewrite it when it hides who did what or what changed.
+
+**Revision-integrity gate.** Compare the rewrite with both the source and the failed wording. Reject a revision when it replaces one vague noun with another, converts one hidden action into a different abstraction, adds parentheses around the same unclear phrase, or drops a qualifier to create fluency. The revised passage must make the concrete actor, action, object, and observable result easier to recover without weakening the proposition.
+
 ### The specialized-term gate
 
 Do not expose internal product, operational, analytical, or methodological terminology merely because it is accurate.
@@ -463,14 +486,13 @@ Where this warning fails: internal boredom and a genuine template tell look iden
 
 When copy fails these tests:
 
-1. Preserve the underlying fact.
-2. Identify the concrete actor, action, object, and result.
+1. Preserve the underlying fact and every material qualifier.
+2. Rewrite the full sentence or short passage through `The literal clarity rewrite`.
 3. Remove internal process language unless the reader needs it.
-4. Split overloaded sentences.
-5. Replace abstractions with observable actions or conditions.
-6. Restore necessary context that compression removed.
-7. Rewrite the call to action to name its actual destination.
-8. Test the revision again.
+4. Split overloaded sentences and distribute their qualifications.
+5. Compare the revision with both the factual draft and the failed wording.
+6. Rewrite the call to action to name its actual destination.
+7. Test the revision again.
 
 Do not repair unclear writing by adding more jargon, explanatory parentheses, longer noun phrases, or vague supporting sentences. Those raise word count and decoding effort at the same time.
 
@@ -482,6 +504,11 @@ Run all of these before accepting customer-facing writing.
 |---|---|
 | First-read | Can the intended reader restate the sentence after one reading? |
 | Actor-action-object | Is it clear who or what acts, what the action is, and what it affects? |
+| Generic referent | Does every generic system or category noun identify the concrete thing it means when ambiguity is possible? |
+| Observable result | Can the reader tell what a person could see happen, separately from how the event was classified or interpreted? |
+| Metaphor recovery | If the metaphor is removed, does the sentence still state the literal mechanism, test, or consequence? |
+| Qualification distribution | Does the short passage preserve every material qualifier without forcing them into one sentence? |
+| Revision integrity | Does the rewrite remove the original decoding work instead of renaming it or hiding it elsewhere? |
 | Delivery-model ownership | Does the provider or product still perform the work the offer sells, without invented or magnified buyer burden? |
 | Rewrite regression | Does every source strength outside the requested transformation survive or materially improve? |
 | Abstraction | Can any abstract noun be replaced with a concrete action, object, condition, or result? |
@@ -1384,7 +1411,7 @@ The comprehension and CTA rules were tested against the research literature afte
 
 What survived with real support: jargon measurably reduces processing fluency; naming an actor changes how readers assign cause ([Fausey and Boroditsky, 2010](https://doi.org/10.3758/PBR.17.5.644)); word frequency predicts processing ease; controls should describe their own destination; one canonical label per materially identical action ([W3C, Link Purpose](https://www.w3.org/WAI/WCAG22/Understanding/link-purpose-link-only.html), [NN/g, Consistency and Standards](https://www.nngroup.com/articles/consistency-and-standards/)); persuasion knowledge makes visible motive costly ([Campbell and Kirmani, 2000](https://academic.oup.com/jcr/article-abstract/27/1/69/1791556)); reading aloud improves error detection.
 
-Two findings in this section are house observations from a diagnosed production failure rather than literature: a sentence carrying its full qualification set inline reads as a compliance memo, and a set of marketing headings built on one template reads as generated. Both were observed directly. Neither has a measured effect size.
+The qualification, heading-variance, generic-referent, observable-result, metaphor-recovery, and revision-integrity procedures are house responses to diagnosed production failures rather than measured response laws. They were observed directly in delivered copy. None has a measured effect size. Use them to remove documented decoding work, not to claim a universal reading or conversion effect.
 
 Remaining governance defaults, explicitly not findings: the twelve-headline template-concentration window, and the review trigger for a sentence carrying two or more reader-unowned terms.
 
@@ -1497,6 +1524,7 @@ Change record:
 
 | Date | Change |
 |---|---|
+| 2026-08-13 | Replaced the broad symptom-led comprehension pass with a mandatory draft-twice, return-once literal clarity rewrite. Added contextual gates for generic referents, observable results, metaphors that hide literal meaning, distributed qualification, noun stacks, and revisions that rename rather than remove ambiguity. Extended technical visual guidance to require label clearance and rendered inspection before legibility claims. |
 | 2026-08-09 | Ran the graded research pass against the seven load-bearing claims. Removed four refuted thresholds: the per-sentence unfamiliar-concept limit, the abstract-noun count, the two-or-three-sentence passage unit, and universal heading-template uniqueness. Rebased abstraction control on actor recovery, the verb guidance on word frequency, the slogan-CTA rejection on operational ambiguity rather than a conversion claim, and mechanism naming on the separate awareness and sophistication axes. Split corpus variance by function so parallel syntax survives where it is functional metadata. Added the pronoun-ranking prohibition and the label-consistency boundary. |
 | 2026-08-09 | Marked the new comprehension and CTA rules HOUSE and provisional, and recorded the seven unsourced load-bearing claims in `Evidence register` pending a graded research pass. |
 | 2026-08-09 | Added `Plain language and first-read comprehension`. Raised comprehension to level 3 of the conflict hierarchy and resolved its two standing conflicts with material qualification and with citability. Rebuilt `CTA standard` around action labels, destination clarity, and cross-surface consistency. Scoped passage self-containment to the passage rather than the sentence. Added the differentiation counterweight to `Mechanism and differentiation`, corpus-level repetition to `Structural tells`, six applied pairs across new business types, and matching invariants and quality dimensions. |