docs(freeticket-cli): document inventory, attendees + sales/export filters

[LucasLeguizamo]

What

Updates the freeticket-cli skill to match the CLI's contract sync (AppFreeticket/freeticket-cli#15):

• Adds ft reports inventory and ft reports export attendees to the command tables.
• Documents the new ft sales list and export filter flags.
• Adds a "tickets left to sell per event" recipe (ft reports inventory --group-by event), the original friction that motivated the inventory endpoint.

Note

Pairs with the CLI PR; merge after (or alongside) it so the docs match the published binary.

🤖 Generated with Claude Code

[qodo-code-review]

PR Summary by Qodo

Document freeticket-cli inventory report and sales/export filtering

📝 Documentation 🕐 10-20 Minutes

AI Description

• Document new ft reports inventory command and its grouping/time-range flags.
• Add ft reports export attendees and clarify buyers vs attendees export semantics.
• Expand ft sales list docs with new filtering flags and an inventory recipe.

Diagram

graph TD
  U([User]) --> S["ft sales list"] --> SF["Sales filters"]
  U --> I["ft reports inventory"] --> IG["Group-by / date range"]
  U --> E["ft reports export buyers|attendees"] --> EF["Export filters"]

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Auto-generate command tables from CLI help/spec

• ➕ Prevents docs drifting from the published binary contract
• ➕ Reduces ongoing manual maintenance for flags and subcommands
• ➖ Requires build tooling and a source-of-truth format (help output parsing or a schema)
• ➖ May reduce ability to add narrative notes inline with tables

2. Link to upstream CLI docs instead of duplicating tables

• ➕ Single source of truth; fewer updates required in this repo
• ➕ Always reflects the latest released CLI behavior
• ➖ Worse offline/readability experience within the skill
• ➖ Harder to keep skill-specific recipes and conventions close to the command reference

Recommendation: The PR’s approach (manually updating the skill docs alongside the CLI contract change) is appropriate for keeping the skill self-contained and immediately useful. If doc drift becomes recurring, consider auto-generating the command tables from a CLI spec/help snapshot while retaining a small hand-written section for recipes (like the inventory group-by example).

Files changed (2) +10 / -4

Documentation (2) +10 / -4

SKILL.mdUpdate skill command table and add inventory usage recipe +6/-2

Update skill command table and add inventory usage recipe

• Expands the 'ft sales list' entry to document the new filter flags. Adds 'ft reports inventory' and 'ft reports export attendees' to the command table and includes a concrete recipe for computing tickets left to sell per event via '--group-by event'.

skills/freeticket-cli/SKILL.md

commands.mdExpand command reference for sales filters and new report/export commands +4/-2

Expand command reference for sales filters and new report/export commands

• Updates the 'ft sales list' reference to include channel/event/date/reference/buyer filters. Adds 'ft reports inventory' (including '--include-drafts' and group-by options) and documents export semantics for buyers (per sale) and attendees (per ticket) with shared filters.

skills/freeticket-cli/references/commands.md

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (2) 📘 Rule violations (0) 📜 Skill insights (0)

1. Inventory flags contradict docs 🐞 Bug ≡ Correctness

Description

SKILL.md documents ft reports inventory without --include-drafts and without the allowed
--group-by values, but references/commands.md documents both. This creates conflicting guidance
inside this repo and can cause users to miss supported filters or pass unsupported --group-by
values.

Code

skills/freeticket-cli/SKILL.md[R51-52]

+| `ft reports inventory` | Capacity/sold/reserved/available (`--event` `--event-date` `--from` `--to` `--group-by`) | VIEWER |
+| `ft reports export buyers\|attendees\|subscribers` | Export buyers (per sale) / attendees (per ticket) / subscribers | ADMIN |

Evidence

The skill’s top-level command table lists a reduced set of inventory flags, while the command
reference explicitly documents an additional flag and the group-by enum, so the two sources disagree
about the command contract.

skills/freeticket-cli/SKILL.md[39-55]
skills/freeticket-cli/references/commands.md[24-42]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`skills/freeticket-cli/SKILL.md` lists `ft reports inventory` flags, but it omits `--include-drafts` and does not document the allowed `--group-by` values, while `skills/freeticket-cli/references/commands.md` includes both. This makes the docs inconsistent and can mislead users.

## Issue Context
The detailed reference already lists: `--include-drafts` and `--group-by ticketType|date|event`.

## Fix Focus Areas
- skills/freeticket-cli/SKILL.md[46-52]
- skills/freeticket-cli/references/commands.md[32-40]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

2. Inventory output shape unclear 🐞 Bug ⚙ Maintainability

Description

The new inventory recipe uses jq '.[]', which assumes ft reports inventory --json outputs a
top-level JSON array of rows. The docs do not state the JSON shape for reports inventory, so the
recipe can be confusing or non-functional depending on whether the command returns an array or a
wrapped object.

Code

skills/freeticket-cli/SKILL.md[R79-80]

+# tickets left to sell per event (one aggregated call, no per-sale fan-out)
+ft reports inventory --group-by event --json | jq '.[] | {eventName, available}'

Evidence

The recipe explicitly iterates over the top-level JSON with .[], but the documentation does not
define the inventory report’s JSON structure; additionally, the reference doc explains a wrapped `{
data, page }` structure for list outputs, which increases the likelihood of confusion without an
explicit inventory-shape note.

skills/freeticket-cli/SKILL.md[67-83]
skills/freeticket-cli/references/commands.md[52-61]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
A new recipe pipes `ft reports inventory --json` into `jq '.[] | ...'`, which assumes the command emits a top-level array. The docs don’t explicitly describe `reports inventory` JSON output shape, and elsewhere the docs explain wrapped list pagination shapes.

## Issue Context
If `reports inventory` returns a wrapped object (e.g., `{ data: [...], page: ... }`) or any other non-array shape, the recipe won’t behave as intended. If it does return an array, a brief note would prevent confusion.

## Fix Focus Areas
- skills/freeticket-cli/SKILL.md[67-83]
- skills/freeticket-cli/references/commands.md[52-61]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

[qodo-code-review]

1. Inventory flags contradict docs 🐞 Bug ≡ Correctness

SKILL.md documents ft reports inventory without --include-drafts and without the allowed
--group-by values, but references/commands.md documents both. This creates conflicting guidance
inside this repo and can cause users to miss supported filters or pass unsupported --group-by
values.

Agent Prompt

## Issue description
`skills/freeticket-cli/SKILL.md` lists `ft reports inventory` flags, but it omits `--include-drafts` and does not document the allowed `--group-by` values, while `skills/freeticket-cli/references/commands.md` includes both. This makes the docs inconsistent and can mislead users.

## Issue Context
The detailed reference already lists: `--include-drafts` and `--group-by ticketType|date|event`.

## Fix Focus Areas
- skills/freeticket-cli/SKILL.md[46-52]
- skills/freeticket-cli/references/commands.md[32-40]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

[qodo-code-review]

2. Inventory output shape unclear 🐞 Bug ⚙ Maintainability

The new inventory recipe uses jq '.[]', which assumes ft reports inventory --json outputs a
top-level JSON array of rows. The docs do not state the JSON shape for reports inventory, so the
recipe can be confusing or non-functional depending on whether the command returns an array or a
wrapped object.

Agent Prompt

## Issue description
A new recipe pipes `ft reports inventory --json` into `jq '.[] | ...'`, which assumes the command emits a top-level array. The docs don’t explicitly describe `reports inventory` JSON output shape, and elsewhere the docs explain wrapped list pagination shapes.

## Issue Context
If `reports inventory` returns a wrapped object (e.g., `{ data: [...], page: ... }`) or any other non-array shape, the recipe won’t behave as intended. If it does return an array, a brief note would prevent confusion.

## Fix Focus Areas
- skills/freeticket-cli/SKILL.md[67-83]
- skills/freeticket-cli/references/commands.md[52-61]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

[LucasLeguizamo]

Superseded by #7 (merged) + #8. Those document reports inventory, export attendees, and the sales list/export filters covered here, plus the rest of the v0.6.0 surfaces (tickets, sales create, discounts, webhooks, plans subscribers, subscriptions cancel, reports by-event/timeseries). This branch was cut from an older main and now conflicts, so closing in favor of #8 to avoid double review.