Update to CodeQR - Link and QR Analytics

{
  "description": "Report how CodeQR QR codes and short links are performing - scan and click counts, trend over time, top cities, devices and referrers, and which codes lead. Triggers on how many scans, how many clicks, which cities, best performing, or any request for a campaign report. Not for creating or editing codes, and not for conversion or revenue reporting.",
  "included_files": [
    {
      "relative_path": "agents/openai.yaml",
      "size_in_bytes": 575
    }
  ],
  "name": "qr-analytics-report",
  "skill_md_contents": "---\nname: qr-analytics-report\ndescription: Report how CodeQR QR codes and short links are performing - scan and click counts, trend over time, top cities, devices and referrers, and which codes lead. Triggers on how many scans, how many clicks, which cities, best performing, or any request for a campaign report. Not for creating or editing codes, and not for conversion or revenue reporting.\n---\n\n# Scan and click reports\n\nAnswer performance questions from recorded CodeQR data through `get_analytics`.\nNever estimate, extrapolate, or fill a gap with a plausible number.\n\n## The two parameters that are always required\n\n`get_analytics` requires **both** `event` and `groupBy` on every call. Omitting\neither one fails the call.\n\n### `event` — pick by resource type, not by phrasing\n\n| Resource | `event` |\n|---|---|\n| QR code | `scans` |\n| Short link | `clicks` |\n\nThis is the trap in this workflow. Asking for `clicks` on a QR code does not\nerror — it returns a well-formed response with nothing in it, which reads exactly\nlike a code nobody scanned. If a result comes back empty, check that the event\ntype matches the resource before reporting zero.\n\n`leads`, `sales` and `composite` also exist, but conversion reporting is out of\nscope for this skill.\n\n### `groupBy` — shape of the answer\n\nValid values: `count`, `timeseries`, `countries`, `cities`, `devices`,\n`browsers`, `os`, `referers`, `top_links`, `top_qrcodes`, `top_urls`.\n\nDo not pass `clicks`, `scans` or `views` as a `groupBy`. The upstream API accepts\nthem and currently answers 500, so they are not offered here.\n\n## Scoping and window\n\n- One QR code: `qrcodeId`. One link: `linkId`. Either can also be reached with\n  `domain` plus `key`.\n- Omit all of them for the whole workspace.\n- `interval` accepts `1h`, `24h`, `7d`, `30d`, `90d`, `ytd`, `1y` and `all`. It\n  defaults to `24h`, which is short enough to look like a dead code if the user\n  meant \"ever\" — so pass it explicitly whenever the question implies a window.\n- Map the user's words to the closest of those and **say which window you used**.\n  \"This year\" is `ytd`, not `90d`. \"Ever\" or \"in total\" is `all`.\n\n### Long windows depend on the plan\n\nThe API refuses windows above the workspace's plan limit with a 403. It is not\nan empty result and not a permissions error the user can fix by re-authorizing:\n\n| Plan | Longest window | Refused |\n|---|---|---|\n| free | 30 days | `90d`, `ytd`, `1y`, `all` |\n| starter | 90 days | `ytd`, `1y`, `all` |\n| pro | 1 year | `all` |\n| business and above | no limit | — |\n\n`get_workspace` returns the plan. Call it once before a report that needs a long\nwindow, rather than discovering the limit through a rejection.\n\nWhen the plan blocks the window the user asked for, report the longest one\navailable, say which plan limit applied, and let them decide — do not silently\nsubstitute a shorter window and present the number as the answer to what they\nasked.\n\n## Build the report in this order\n\n1. **Headline** — `groupBy: \"count\"` for the total over the window.\n2. **Trend** — `groupBy: \"timeseries\"` only when the user asks how it is moving,\n   or when the answer is about growth or decline.\n3. **One or two breakdowns** — `cities` or `countries` for where, `devices` or\n   `os` for how, `referers` for where the traffic came from.\n4. **Ranking across codes** — `top_qrcodes` for scans, `top_links` for clicks.\n\nEach of these is a separate call. Run only the ones the question needs: four\nbreakdowns nobody asked for buries the answer instead of supporting it.\n\n## Reporting rules\n\n- Lead with the number the user asked for, then the context.\n- Always state the window and the scope alongside the number. \"1,240 scans\" on\n  its own is not an answer; \"1,240 scans in the last 30 days, for the menu QR\n  code\" is.\n- If a query returns empty, report it as no recorded data for that window and\n  scope. Do not present it as zero performance without checking the `event` type\n  first, and never substitute a made-up figure.\n- Scans and clicks are recorded per code with time, country, city and device.\n  Personal identity is not part of this data, so do not describe results as\n  individual people.\n"
}