From cf508540fab5c13ab9ec22ffe1a6c188fd269711 Mon Sep 17 00:00:00 2001 From: Ilia Sidorenko Date: Fri, 29 May 2026 11:07:03 -0400 Subject: [PATCH] fix inaccuracies in `stqry skill` reference and workflow docs --- CHANGELOG.md | 1 + internal/skills/stqry-reference.md | 80 ++++++++++++++++++++++++++---- internal/skills/stqry-workflows.md | 2 +- 3 files changed, 72 insertions(+), 11 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index ccfcb72..d8326d6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -15,6 +15,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - Aligned CLI flag types, values and validation with what the public API actually accepts: `codes --max-redemptions 0` / `--expire-after 0` now send `null` (unlimited / clear) rather than 422; `maps paths --cost` is an integer and `--cost-override` a boolean; `maps paths --direction` accepts `bidirectional | forward | backward`; `maps layers features create` requires `--name`; `collections items --radius` is guarded `>= 1`; `screens sections prices`/`hours` honour `--lang` for their translated fields; `CrossRegionLink` is rejected client-side for collection-item and link-item types; media types validate through one shared `api.ValidateMediaType`; and `codes list --sort-field` no longer advertises the unsupported `redemptions`. - Corrected MCP tool contracts: `list_collection_items` returns its rows under a `collection_items` key (was a generic `items`); `create_collection`/`screen`/`section`/`code`/`media`/`map_feature` document their server-required fields; pagination params are described consistently (server default 30, max 1000) instead of four contradictory phrasings; `delete_media` gained a per-locale `language` arg; and `update_collection`/`update_screen` note the `primary_language`-flip caveat. +- Fixed inaccurate skill reference and workflow docs: dropped the non-existent `exhibit` collection type and the "codes link to screens" claim, resolved the self-contradictory `--lang`-on-reads note, corrected the `maps path-nodes`/`paths` flag signatures, documented the `0 = unlimited` code sentinel and the `--radius >= 1` minimum, and quoted the real opening-time sub-item 422 message. ## [0.10.33] - 2026-05-28 diff --git a/internal/skills/stqry-reference.md b/internal/skills/stqry-reference.md index b2e82bd..2fc26cb 100644 --- a/internal/skills/stqry-reference.md +++ b/internal/skills/stqry-reference.md @@ -57,6 +57,9 @@ Top-level entities (all exist independently): Screens └── Sections └── Sub-items (hours, links, badges, prices, social, media) + Quizzes + └── Questions (position-ordered) + └── Answers (position-ordered) Media Items Uploaded Files (the binaries Media Items reference) Codes @@ -79,12 +82,13 @@ Collections are composed via Collection Items (join records): **Collection Items are join records**, not content containers. A collection item has two fields: `item_type` (`"Screen"` or `"Collection"`) and `item_id` (the ID of the referenced entity). The referenced entity must exist before the collection item is created — create screens first, then link them into collections. - **Projects** — top-level organisational units; each project belongs to one STQRY account. -- **Collections** — groupings of screens or other collections. Each collection has a type (tour, exhibit, etc.). +- **Collections** — groupings of screens or other collections. Each collection has a type: one of `list`, `tour`, `organization`, `menu`, `search`. - **Screens** — standalone content pages. A screen has sections and can be linked into one or more collections. - **Sections** — content blocks within a screen (text, image, audio, video, etc.). - **Sub-items** — structured data attached to a section: hours, links, badges, prices, social handles, media. +- **Quizzes** — interactive quizzes. A quiz has questions; each question has answers. A quiz is surfaced in an app by a `quiz_question` / `quiz_score` story section on a screen. - **Media Items** — images, audio, video, and documents. Can be uploaded and attached independently. -- **Codes** — redemption codes that deep-link into collections or screens. +- **Codes** — redemption codes that deep-link into a collection or a whole project (`--linked-type Collection | Project`). (Not individual screens — the public API's `linked_type` enum is `Collection` / `Project`.) --- @@ -270,9 +274,9 @@ done ### Language Support -- When `--lang` is omitted, **writes** use the account's `settings.default_content_language` (looked up once per CLI invocation via `GET /api/public/account` and cached). On older API servers that don't expose `/api/public/account`, the CLI silently falls back to `en`. **Reads** that take an optional `language` query param (e.g. `stqry media list`, `stqry media get`) leave it unset when `--lang` is omitted, letting the API return its default representation. -- Pass `--lang ` to override the account default for a single command. -- `get` subcommands always return the full translation map for every translated field; `--lang` on a `get` has no effect and prints a stderr warning to surface the misuse. To extract a single locale's value, pipe through `--jq` (e.g. `stqry screens get 1 --jq '.title.en'`). +- When `--lang` is omitted, **writes** (create / update, and `media upload`) use the account's `settings.default_content_language` (looked up once per CLI invocation via `GET /api/public/account` and cached). On older API servers that don't expose `/api/public/account`, the CLI silently falls back to `en`. +- Pass `--lang ` to override the account default for a single command — it sets the locale key under which translated fields are written. +- **Reads** (`get`, `list`, `appears-in`) always return the full translation map for every translated field — no read endpoint takes a `language` query param, so `--lang` on a read has no effect and prints a stderr warning to surface the misuse. To extract a single locale's value, pipe through `--jq` (e.g. `stqry screens get 1 --jq '.title.en'`). - Language codes follow IETF BCP 47 (e.g. `en`, `fr`, `de`, `zh-Hans`); validated client-side against the canonical list (`stqry config languages`). --- @@ -340,7 +344,7 @@ stqry collections appears-in Show every place this collection stqry collections items list List items in a collection stqry collections items get Get a single collection item stqry collections items add --item-type --item-id [--position ] Add a screen or collection to a collection -stqry collections items update [--position ] [--lat ] [--lng ] [--item-number ] [--geofence ] [--radius ] [--geofence-lat ] [--geofence-lng ] [--geofence-content] Update a single collection item (position, GPS pin, geofence). --radius merges into gps_settings so existing geofence_lat / geofence_lng aren't clobbered. Bulk with a shell loop — see the geofence snippet below. +stqry collections items update [--position ] [--lat ] [--lng ] [--item-number ] [--geofence ] [--radius ] [--geofence-lat ] [--geofence-lng ] [--geofence-content] Update a single collection item (position, GPS pin, geofence). --radius merges into gps_settings so existing geofence_lat / geofence_lng aren't clobbered. Bulk with a shell loop — see the geofence snippet below. stqry collections items reorder ... Reorder items in a collection (positions applied to the whole list; the bulk-reorder endpoint is 1-based — the singular `--position` flag on `add`/`update` is 0-based) stqry collections items remove Remove an item from a collection ``` @@ -394,7 +398,62 @@ stqry screens sections social list|add|update|remove --screen-id --sectio stqry screens sections hours list|add|update|remove --screen-id --section-id ``` -**Link items.** The `--link-type` enum is the full set `twitter, whatsapp, wechat, facebook, instagram, pinterest, youtube, vimeo, linkedin, tiktok, weibo, bluesky, internal, url, email, phone, live_tours, settings, badges, favourites, download, app_rating, search`. For a URL link use `--link-type url --url --link-text