positioning cards

Invocation#

echo-cli positioning cards --product <id> [--competitor <name>]
echo-cli positioning card --product <id> --competitor <name> --pages <https-url,...> --by <name>
echo-cli positioning export --card <id> --out <file.md>
echo-cli positioning refresh --by <name>

Inputs and output#

cards writes every version, newest first, and card the version it stored: id, product_id, competitor, version, competitor_urls, capture_ids, fact_sheet_id, sections (about: pricing, strengths and weaknesses, each a list of claim, capture_id, url, captured_at and quote; how_we_win: reason and the facts it cites; objections: claim — the objection as a prospect says it — capture_id, url, captured_at, quote, answer and the facts the answer cites, absent from versions written before cards carried objections; dropped: how many claims and objections the route wrote that did not quote a capture word for word), route, created_by and created_at. export writes the version as Markdown to --out — the heading with its version, pricing, their strengths and their weaknesses with each quote, page and capture time, why we win with its facts, the objections with their answers, and the dropped count — and prints card_id, path (absolute) and bytes. refresh writes, per card it refreshed, card_id, product_id, competitor, refreshed (the new version) and error.

State effect#

The verbs call Echo Web's authenticated /api/analytics/battlecards with ECHO_INTERNAL_BEARER at ECHO_WEB_BASE_URL (export reads GET ?id=<card>, answered as { card, markdown }); the Battlecards section of the blog admin and of Echo Desktop's GEO screen do the same, with a Markdown download per version, echo-mcp runs them as echo_battlecards, echo_battlecard_markdown, echo_battlecard_write and echo_battlecards_refresh, and /api/cron/battlecards refreshes daily at 05:37 UTC, after the competitor captures. card reads the latest readable capture of each --pages page (echo-cli competitors capture) and the product's fact sheet in force, and has the route ECHO_BATTLECARD_ROUTE declares write the card through Brama. Cards are stored in battlecards as versions; a card is stale when one of its pages has a newer readable capture than the one it read, and refresh writes the next version of each stale card, keeping the old ones. export writes only from the stored version and calls no model.

Refusals#

• A wrong invocation is refused before anything is sent: "positioning <verb> does not take <flag>; it takes …", "<flag> needs a value" and "positioning <verb> needs <flag>".
• export is refused with "id is required: the battlecard version to export, as echo-cli positioning cards lists it" and not found with "no battlecard has id <id>"; a --out the CLI cannot write is the error naming the path. card is also refused with "the route <route> wrote an objection answer citing no fact of fact sheet <id>; nothing was stored", and fails with "the route <route> wrote objections that is not a list" when the route answers without them.
• Echo Web answers a bad request with "product_id is required: the product the card sells" (reading: "the product whose battlecards are read"), "competitor is required: the competitor the card is against", "competitor_urls is required: the competitor pages the card quotes, as a non-empty list", "url must be an absolute https address; got <value>", "created_by is required: an internal caller has no signed-in user, so it names who is acting" (and refreshed_by), "the route <route> wrote a reason to win citing no fact of fact sheet <id>; nothing was stored" or "the route <route> wrote \"<reason>\" citing <names>, which fact sheet <id> does not hold; nothing was stored"; not found with "no product has id <id>; echo-cli products lists the ones that exist", "product <id> has published no fact sheet; publish one with echo-cli geo facts publish" or "<url> has no readable capture; echo-cli competitors capture --url <url> captures it"; and fails with "ECHO_BATTLECARD_ROUTE is required" when the route is not declared. The command prints Echo Web's sentence and exits 1.