seo glossary

Invocation#

echo-cli seo glossary add --post <post-id> --term <term> --definition <text> [--related <term,term…>] [--product-pages <https-url,…>] --by <who> | list --surface <surface-slug> | remove --post <post-id>

Inputs and output#

add and remove write the entry: post_id, surface_slug, term, definition, related (terms of the surface's other entries), product_pages (the https addresses of the product pages it links to, in the order given), declared_by and declared_at. list writes { entries } of the surface by term. The public payload's glossary carries productPages, the same addresses, beside related, so a landing links the entry to the product.

State effect#

Every verb calls Echo Web's authenticated /api/seo/glossary with ECHO_INTERNAL_BEARER at ECHO_WEB_BASE_URL; the Glossary entries section of the blog admin and of Echo Desktop's GEO screen call the same operations, and echo-mcp runs them as echo_glossary_entry, echo_glossary_entries and echo_glossary_entry_remove. Entries are kept in blog_glossary_entries, one per post and one per term of a surface, compared case-blind; an entry added without --related relates to no other entry. The public payload of a published entry, /api/public/blog/<surface>/<slug>, answers glossary: definedTerm, the term as a schema.org DefinedTerm in the surface's DefinedTermSet, and related, the related entries that are published with their addresses; it answers jsonLd, the post's BlogPosting, for every post, and glossary null for a post that is no entry.

Refusals#

• A wrong invocation is refused before anything is sent: "seo glossary takes <every verb's usage, separated by semicolons>; got <word>", "seo glossary <verb> does not take <flag>; it takes …", "<flag> needs a value" and "seo glossary <verb> needs <flag>".
• Echo Web answers a bad request with "post_id is required: the blog post that is the entry", "term is required: the term the entry defines", "definition is required: what the term means, in one or two sentences", "declared_by is required: who declares the entry" or "surface is required: the blog surface whose glossary to read"; not found with "no blog post has id <id>", "<surface> has no glossary entry for <terms>; declare those entries first" or "post <id> is not a glossary entry; echo-cli seo glossary list --surface <slug> lists them"; a conflict with "<surface> already defines <term> as post <id>" or "<terms> relate to <term>; remove the relation first"; and fails naming the cause with "the glossary entry for <term> could not be stored: <cause>" or "the glossary entry of post <id> could not be removed: <cause>". The command prints Echo Web's sentence and exits 1.
• Echo Web refuses an entry whose lists are not lists with "related must be a list of the terms of the same surface the entry relates to; [] when there are none" or "product_pages must be a list of the https addresses of the product pages the entry links to; [] when there are none", and a product page that is not an absolute https address with "product_pages must hold absolute https addresses; got <value>"; echo-cli sends [] for a list flag not given.