docs(freeticket-cli): settlements/api-keys + skill freeticket-mcp + el repo como plugin instalable

[LucasLeguizamo]

La skill se quedó atrás del CLI. Faltaban comandos que ya existen (ft api-keys desde 0.8.0) y los que llegan con freeticket-cli#33.

• ft settlements list y ft reports financials. Van con una nota explícita: la respuesta correcta a "cuánto se le liquida al organizador" es leer los números que FreeTicket ya calculó, no hacer aritmética sobre sales list. Es el error que un agente comete solo si nadie se lo dice.
• ft api-keys create|list|revoke — credencial headless para CI/cron; el plano sale una sola vez.
• ft admin tokens list|create|revoke — reemplaza pasear la cookie better-auth.session_token por los scripts.
• ft events list --q.
• Confirmación y exit codes: un abort sale 1 y sin TTY el comando falla de inmediato, así que ft … delete && next-step no ejecuta next-step. Documentado para que --yes se pase a propósito y no por costumbre.
• El PDF de comprobante de liquidación no se baja por API (solo panel) — dicho para que nadie lo busque.

Versión mínima documentada: ft ≥ 0.9.0.

---

Además: skill freeticket-mcp y el repo como plugin instalable

Skill freeticket-mcp — setup local (stdio) y remoto (connector en claude.ai vía el AS OAuth 2.1 embebido), las tres capas de credenciales (anónimo B2C → workspace B2B → superadmin), los 87 tools y qué queda deliberadamente afuera. El README ya la listaba en esta branch; ahora existe.

El repo es un plugin. Ya tenía el layout que pide Agent Plugins 1.0.0 (skills/<name>/SKILL.md en la raíz), así que solo faltaban manifests — sin mover archivos y sin el repo freeticket-plugin aparte que preveía el roadmap:

Archivo	Para qué
plugin.json + mcp.json	Estándar Agent Plugins 1.0.0 — portable a cualquier cliente compatible. Validados contra los schemas oficiales.
.claude-plugin/plugin.json	Claude Code, que todavía no lee el layout del estándar. Apunta a ./mcp.json con mcpServers en vez de duplicar la definición del server.
.claude-plugin/marketplace.json	Canal de instalación de Claude Code, en este mismo repo: un repo de marketplace aparte para listar un solo plugin no se paga.

El plugin declara el server remoto mcp.appfreeticket.com/mcp, que autoriza por OAuth en el browser al primer uso. Primero se había puesto el stdio npx -y @freeticket/mcp y no funciona: el paquete nunca se publicó en npm — el plugin registraba el server y moría con "Connection closed". Queda anotado como hito 11 del roadmap, y el skill freeticket-mcp lo avisa hasta que se publique.

Instalación (probada de punta a punta contra esta branch, no solo validate):

/plugin marketplace add AppFreeticket/agent-skills
/plugin install freeticket@freeticket

→ las 3 skills en el cache y plugin:freeticket:freeticket en claude mcp list.

claude plugin validate pasa en los dos manifests. Contexto en AppFreeticket/ai-native → ROADMAP-AI-FIRST.md, hito 6.

🤖 Generated with Claude Code

[qodo-code-review]

PR Summary by Qodo

Update FreeTicket CLI docs for settlements, financial reports, and tokens

📝 Documentation 🕐 10-20 Minutes

AI Description

• Document ft ≥ 0.9.0 commands: settlements, financial reports, API keys, and admin tokens.
• Clarify authoritative payout/financial workflow (reports financials → settlements list) and
 PDF limitations.
• Explain destructive-command confirmation behavior (TTY, exit codes) for safer scripting.

Diagram

graph TD
  U["User / CI script"] --> CLI["ft CLI"] --> V1[["B2B API v1"]] --> FIN["Financials & settlements"]
  U --> CLI --> KEYS["API keys (ft_live)"]
  U --> CLI --> ADM[["Admin API"]] --> TOK["Admin tokens (PAT)"]

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Generate command reference from OpenAPI/CLI help output

• ➕ Reduces doc drift as new commands/flags ship
• ➕ Enables versioned docs aligned to CLI releases
• ➕ Lowers maintenance cost for large command surfaces
• ➖ Requires building and maintaining a docs-generation pipeline
• ➖ May miss nuanced guidance (e.g., payout interpretation, scripting caveats) unless supplemented

2. Add a “What’s new since X.Y” changelog section in docs

• ➕ Makes upgrades/behavior changes discoverable (e.g., exit codes, tokens)
• ➕ Smaller maintenance burden than full doc generation
• ➖ Still requires manual updates and can drift over time
• ➖ Doesn’t guarantee the main command tables stay complete

Recommendation: For immediate correctness, this PR’s manual updates are the right move because they add critical operational guidance (authoritative financial numbers, confirmation/TTY behavior) that auto-generated docs might omit. Longer-term, consider generating the command tables from the CLI/OpenAPI and keeping a small hand-written guidance layer to prevent future drift.

Files changed (2) +52 / -4

Documentation (2) +52 / -4

SKILL.mdBump minimum CLI version and document new financial/token workflows +19/-3

Bump minimum CLI version and document new financial/token workflows

• Updates the documented minimum 'ft' version to ≥ 0.9.0 and adds new commands ('reports financials', 'settlements list', 'api-keys', 'admin tokens'). Also clarifies destructive-command confirmation behavior (TTY + exit code 1 on abort) and explicitly directs money questions to 'reports financials'/'settlements' (including the panel-only proof PDF limitation).

skills/freeticket-cli/SKILL.md

commands.mdExpand CLI command reference with search, settlements/financials, and token/key sections +33/-1

Expand CLI command reference with search, settlements/financials, and token/key sections

• Adds '--q' support to 'ft events list' in the reads table and documents 'settlements list', 'reports financials', and 'api-keys list'. Introduces explanatory sections for settlements vs. financial reports, plus a dedicated service-credentials section for 'ft api-keys' and new admin token commands ('ft admin tokens list|create|revoke').

skills/freeticket-cli/references/commands.md

[qodo-code-review]

Code Review by Qodo

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

1. Admin token docs inconsistent 🐞 Bug ≡ Correctness

Description

skills/freeticket-cli/references/commands.md still says a revocable admin service token is
“coming”, but this PR also adds the ft admin tokens list|create|revoke commands, which contradicts
the earlier guidance and can mislead CI/auth setup. The docs also don’t state (based on the actual
CLI interface) how to provide the newly minted plaintext token to later ft admin … commands.

Code

skills/freeticket-cli/references/commands.md[R159-161]

+| `ft admin tokens list` | — (no pagination) | SUPER_ADMIN |
+| `ft admin tokens create` | `--data` (`{"name","expiresAt?"}`) — plaintext shown once | SUPER_ADMIN |
+| `ft admin tokens revoke <id>` | `--yes` to skip confirm | SUPER_ADMIN |

Evidence

The Admin section in commands.md still claims a revocable service token is future work, but the
same file now lists ft admin tokens list/create/revoke. SKILL.md also recommends minting an
admin token for CI without documenting how that token is then provided to the CLI.

skills/freeticket-cli/references/commands.md[126-132]
skills/freeticket-cli/references/commands.md[159-165]
skills/freeticket-cli/SKILL.md[123-129]

Agent prompt

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

### Issue description
The admin authentication section still frames service tokens as future work, but the same reference now documents `ft admin tokens …`. This creates contradictory guidance and also leaves out the critical “how to use the created token” step for headless `ft admin`.

### Issue Context
- The reference currently says tokens are “coming”, while listing the token commands.
- `SKILL.md` advises using `ft admin tokens create` for CI, but neither doc shows (per the real CLI contract/help) how the minted token is supplied to future admin commands.

### Fix Focus Areas
- skills/freeticket-cli/references/commands.md[126-138]
- skills/freeticket-cli/references/commands.md[159-165]
- skills/freeticket-cli/SKILL.md[123-129]
- skills/freeticket-cli/SKILL.md[137-138]

### What to change
1. Remove or rewrite the stale “MVP — a revocable service token replaces this …” wording so it matches the now-documented `ft admin tokens …` feature.
2. Add a short, **verified** snippet showing how the minted admin token is used for subsequent `ft admin` calls (confirm the exact env var / flag from the CLI’s actual behavior/help, then document that mechanism explicitly).

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

---

_{To customize comments, go to the Qodo configuration screen, or learn more in the docs.}

[qodo-code-review]

1. Admin token docs inconsistent 🐞 Bug ≡ Correctness

skills/freeticket-cli/references/commands.md still says a revocable admin service token is
“coming”, but this PR also adds the ft admin tokens list|create|revoke commands, which contradicts
the earlier guidance and can mislead CI/auth setup. The docs also don’t state (based on the actual
CLI interface) how to provide the newly minted plaintext token to later ft admin … commands.

Agent Prompt

### Issue description
The admin authentication section still frames service tokens as future work, but the same reference now documents `ft admin tokens …`. This creates contradictory guidance and also leaves out the critical “how to use the created token” step for headless `ft admin`.

### Issue Context
- The reference currently says tokens are “coming”, while listing the token commands.
- `SKILL.md` advises using `ft admin tokens create` for CI, but neither doc shows (per the real CLI contract/help) how the minted token is supplied to future admin commands.

### Fix Focus Areas
- skills/freeticket-cli/references/commands.md[126-138]
- skills/freeticket-cli/references/commands.md[159-165]
- skills/freeticket-cli/SKILL.md[123-129]
- skills/freeticket-cli/SKILL.md[137-138]

### What to change
1. Remove or rewrite the stale “MVP — a revocable service token replaces this …” wording so it matches the now-documented `ft admin tokens …` feature.
2. Add a short, **verified** snippet showing how the minted admin token is used for subsequent `ft admin` calls (confirm the exact env var / flag from the CLI’s actual behavior/help, then document that mechanism explicitly).

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