positioning

Invocation#

echo-cli positioning list --product <id>
echo-cli positioning generate --product <id> --competitors <https-url,...|-> --by <name>

Inputs and output#

generate writes the canvas it stored and list every version, newest first: id, product_id, version, fact_sheet_id, category, alternatives, differentiators (claim, facts — the fact sheet names it cites — and also_claimed_by: url, capture_id, captured_at and quote for each competitor page whose latest capture claims it too), proof (statement and facts), competitor_urls, route, created_by and created_at.

State effect#

Both verbs call Echo Web's authenticated /api/analytics/positioning with ECHO_INTERNAL_BEARER at ECHO_WEB_BASE_URL; the Positioning canvas section of the blog admin and of Echo Desktop's GEO screen call the same operation, and echo-mcp reads it as echo_positioning_canvases. generate reads the product's fact sheet in force (echo-cli geo facts publish) and has the route ECHO_POSITIONING_ROUTE declares write the canvas through Brama; every differentiator and proof point must cite at least one fact of that sheet by name, and a canvas citing none, or a name the sheet does not hold, is refused with nothing stored. --competitors names competitor pages already captured (echo-cli competitors capture), comma-separated, or - for none; the same route is given each page's latest readable capture and quotes where it claims a differentiator too, and only a quote found word for word in the capture's text flags that differentiator with the page. Each canvas is stored as the next version of the product's canvas, with the fact sheet, the pages checked and the route; earlier versions are kept.

Refusals#

• A wrong invocation is refused before anything is sent: "positioning takes <every verb's usage, separated by semicolons>; got <word>", "positioning <verb> does not take <flag>; it takes …", "<flag> needs a value" and "positioning <verb> needs <flag>".
• Echo Web answers a bad request with "product_id is required: …", "competitor_urls is required: the competitor pages each differentiator is checked against, as a list (empty to check none)", "url is required: the public https page to capture", "url must be an absolute https address; got <value>", and "the route <route> wrote \"<part>\" citing no fact of fact sheet <id>; nothing was stored" or "… 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". A deployment without ECHO_POSITIONING_ROUTE answers "ECHO_POSITIONING_ROUTE is required", and a route that answers without its tool, or with a part that is not text, is the error naming it. The command prints Echo Web's sentence and exits 1.