messaging

Invocation#

echo-cli messaging list --product <id>
echo-cli messaging draft --product <id> --file <house.json> --by <name>
echo-cli messaging approve --id <version-id> --by <name>
echo-cli messaging bind --experiment <id> --arm <variant-key> --version <version-id> --by <name>
echo-cli messaging unbind --experiment <id> --arm <variant-key>
echo-cli messaging bindings --experiment <id>
echo-cli messaging test --experiment <id> --sigmas <standard-errors>

Inputs and output#

list writes houses, every version newest first (id, product_id, version, umbrella, pillars as { title, message, proofs }, created_by, created_at, approved_by, approved_at, retired_by, retired_at), approved, the one approved version or null, and generations, every blog generation run that read one of the versions, newest first (run_id, messaging_house_id, read_at). draft and approve write the version they wrote or approved. bind and unbind write the binding (experiment_id, variant_key, house_id, bound_by, bound_at) they made or removed; bindings writes the experiment's bindings by arm. test writes verdict (the experiment's verdict: each variant's exposures, conversions and rate, the leader's comparisons at --sigmas standard errors and winner, null while any interval reaches 0), arms (each variant's outcome with house, the messaging version it carries or null) and winning_house (the version the winner carried, null without a winner or when the winner carries none).

State effect#

list, draft and approve call Echo Web's authenticated /api/analytics/messaging or /api/analytics/messaging/approve, and bind, unbind, bindings and test call /api/analytics/messaging/tests, with ECHO_INTERNAL_BEARER at ECHO_WEB_BASE_URL; the Messaging house and Message tests sections of the blog admin and of Echo Desktop's GEO screen (pillars typed as the file's JSON list, the generation runs listed under the version they read) call the same operations, and echo-mcp reads the house (echo_list_messaging) and the message test (echo_message_test) but cannot draft, approve or bind. The draft file holds { "umbrella": "…", "pillars": [{ "title": "…", "message": "…", "proofs": ["…"] }] }; only those two fields are read. A draft is the product's next version number. Approving a draft makes it the one approved version and retires the version it replaces in a single database transaction, so a product never has two approved versions; a version is never edited, and a change is a new draft. A version is a draft until approved, approved until another is approved in its place, and then retired. The generators read the approved version and are given its umbrella message, pillars and proof points: a blog generation run of a surface that answers to the product (glossary surface) reads it before researching and keeps the version it read in blog_generation_messaging, which list writes as generations; a short-video script (content scripts write) keeps it as messaging_house_id; a viral format adaptation keeps it as messaging_version; and a draft crafted from an AI: brief for a campaign that speaks for the product (email brand) is written from it. While the product has no approved version, each of them is refused naming the product and echo-cli messaging approve — the generation run fails with that error — and nothing is written past the product's message. A surface or campaign naming no product reads none. A message test binds an adaptive experiment's arms (its variant keys) to versions, stored in experiment_message_variants: an arm carries one version and a version one arm of an experiment. test reads the experiment's verdict as echo-cli experiments outcomes does — exposures from its stored assignments, conversions from its reward event within its reward window — and puts each arm's version beside its outcome and the winner's version beside the winner, so the message that won is named only once every interval clears 0.

Refusals#

• A wrong invocation is refused before anything is sent: "messaging takes <every verb's usage, separated by semicolons>; got <word>", "messaging <verb> does not take <flag>; it takes …", "<flag> needs a value", "messaging <verb> needs <flag>" for each flag the verb needs, "--file <path> is not JSON: <parser's reason>", "--file <path> must hold { umbrella, pillars: [{ title, message, proofs }] }" and "--sigmas must be a number of standard errors; got <value>"; a file that cannot be read ends with the system's error naming the path.
• Echo Web answers a bad request with "product_id is required: …", "umbrella is required: the one message every pillar supports", "pillars is required: at least one { title, message, proofs } the umbrella message rests on", "pillars[<n>] must be { title, message, proofs }", "pillars[<n>].title is required: the pillar's name" (and message, proofs[<n>]), "pillars[<n>].proofs must be the proof points behind the pillar; [] when none are stated yet", "id is required: …", "version <n> is already approved, by <who> at <time>", "version <n> was retired by <who> at <time>; write a new draft to bring it back" or "created_by is required: an internal caller has no signed-in user, so it names who is acting" (approved_by); and not found with "no product has id <id>; echo-cli products lists the ones that exist" or "no messaging house version has id <id>; echo-cli messaging list --product <id> lists them". The command prints Echo Web's sentence and exits non-zero.
• For message tests Echo Web answers a bad request with "experiment_id is required: …", "variant_key is required: …", "house_id is required: …", "bound_by is required: …", "experiment <id> has no arm <key>; its arms are <keys>", "arm <key> of experiment <id> already carries messaging version <version-id>, bound by <who>; unbind it first", "messaging version <n> is already carried by arm <key> of experiment <id>; one version tests in one arm" or "sigmas must be a positive number: how many standard errors each interval spans"; and not found with "no adaptive experiment <id> has variants; echo-cli experiments lists the experiments", "no adaptive experiment has id <id>; echo-cli experiments lists them", "arm <key> of experiment <id> carries no messaging version" or "no arm of experiment <id> carries a messaging version; echo-cli messaging bind binds one". The experiment's own refusals (no reward event or window in its reward_spec) are answered as echo-cli experiments outcomes answers them.