@quantbrasil/cli 0.1.0-beta.1 → 0.1.0-beta.10

package/skills/quantbrasil/references/errors.md

@@ -1,5 +1,15 @@
 # Error Handling
 
+## Binary not found
+
+If `quantbrasil` is not available on `PATH`, report that the CLI binary is not
+installed or not visible to the current shell.
+
+Do not inspect local repositories, package source, or credential files to work
+around a missing binary. The CLI owns auth lookup and backend selection.
+Do not silently fall back to generic web or finance search unless the user
+approves another source.
+
 ## Auth / readiness
 
 Check:
@@ -26,9 +36,9 @@ Treat CLI validation as user-input error.
 
 Examples:
 
-- invalid portfolio id
+- invalid watchlist or holding id
 - invalid `--sections`
-- invalid `--asset TICKER[:WEIGHT_PCT]`
+- invalid `--target TICKER:WEIGHT_PCT`
 - invalid `--years`
 
 Fix input. Do not retry same bad command.
@@ -60,14 +70,15 @@ Stable codes:
 
 Possible causes:
 
-- portfolio id does not exist
+- watchlist or holding id does not exist
 - ticker not tracked
 - requested history unavailable for period
 
 Recovery:
 
 - use `market assets` for discovery
-- use `portfolios list` before `portfolios get`
+- use `watchlists list` before `watchlists get`
+- use `holdings list` before holding metrics
 - narrow period or pick another ticker
 
 Stable code:
@@ -96,7 +107,7 @@ when a requested ticker is invalid for the operation.
 Recovery:
 
 - read the error message
-- fix the requested portfolio id, name, ticker list, or operation
+- fix the requested watchlist/holding id, name, ticker list, or operation
 - do not retry unchanged mutation input
 
 Stable code:

package/skills/quantbrasil/references/portfolios.md

@@ -0,0 +1,114 @@
+# Portfolio Reference
+
+Use this reference whenever the user mentions portfolios, carteiras, holdings,
+watchlists, target weights, positions, historical return, beta, VaR, risk,
+screening universes, or a saved composition.
+
+## Domain model
+
+- `Portfolio` is the umbrella domain term for a user-owned saved asset set.
+- `Watchlist` is a portfolio used for monitoring assets. It has assets, but it
+  is not an investable composition and does not define weights or positions.
+- `Holding` is a portfolio used as an investable composition. It can be based on
+  target weights or positions.
+- `System Portfolio` is a backend-managed portfolio-backed universe exposed by
+  slug for screening discovery and runs.
+- `Screening Universe` is exactly one system portfolio, watchlist, or holding
+  selected for indicator screening.
+- A theoretical portfolio is a holding with target weights. Save it first, then
+  run metrics on the returned holding id.
+- A holding used as a screening universe contributes only its asset set; target
+  weights and positions do not affect indicator screening.
+- Target weights and positions are independent: target weights describe intended
+  allocation, while positions describe actual ownership.
+- Position quantities are shares, units, or coin amounts. Do not pass monetary
+  values as positions in the public CLI.
+
+## Command routing
+
+- Use `quantbrasil watchlists ...` for monitoring lists, ticker groups, and
+  non-investable saved lists.
+- Use `quantbrasil holdings ...` for investable compositions, target weights,
+  positions, historical return, beta, VaR, and risk/return checks.
+- Use `quantbrasil screening universes` to discover system portfolios,
+  watchlists, and holdings available for screening.
+- Use `quantbrasil screening run` with exactly one selector to run indicator
+  screening over that selected asset set.
+- Use `quantbrasil holdings list` when the user names a saved holding but does
+  not provide an id.
+- Use `quantbrasil watchlists list` when the user names a saved watchlist but
+  does not provide an id.
+- If the user asks for portfolio analytics without specifying an object, resolve
+  or create a holding first.
+
+Do not use these patterns:
+
+- `quantbrasil portfolios ...`
+- `quantbrasil analytics ...`
+- ad-hoc asset lists passed directly into metric commands
+- ad-hoc asset lists passed directly into screening commands
+- running holding metrics on a watchlist
+
+## Holdings
+
+Create target-weight holdings when the user wants to analyze a hypothetical or
+model composition.
+
+```bash
+quantbrasil holdings create "Teórica energia" --target VALE3:50 --target PRIO3:50
+quantbrasil holdings historical-return 93 --from 2025-01-01 --to 2026-01-01
+```
+
+`holdings create` returns the holding id. Reuse that id for follow-up commands.
+
+Use `set-targets` to replace a holding target allocation.
+
+```bash
+quantbrasil holdings set-targets 93 VALE3:40 PRIO3:35 PETR4:25
+```
+
+Use position mode only when the user is creating or managing a real position
+holding.
+
+```bash
+quantbrasil holdings create "Carteira Real" --mode position
+quantbrasil holdings set-positions 93 PRIO3:1600 BTC-USD:0.25 QQQ:10
+```
+
+`set-positions` is a partial quantity upsert: it changes only the mentioned
+tickers and leaves unmentioned positions unchanged. It does not clear or replace
+target weights.
+
+## Watchlists
+
+Use watchlists for saved sets of assets that the user wants to monitor, screen,
+or revisit later.
+
+```bash
+quantbrasil watchlists create "Dividendos"
+quantbrasil watchlists add-assets 93 PETR4 VALE3
+quantbrasil watchlists get 93
+```
+
+If the user asks for return, beta, VaR, or risk on a watchlist, explain that a
+watchlist has no investable composition. Create a target-weight holding or use
+an existing holding instead.
+
+## Metrics
+
+Holding metrics always run through `holdings`.
+
+```bash
+quantbrasil holdings historical-return 93 --from 2025-01-01 --to 2026-01-01
+quantbrasil holdings historical-return 93 --period 1y
+quantbrasil holdings beta 93 --years 1
+quantbrasil holdings var 93 --years 1 --confidence 95
+```
+
+Rules:
+
+- `historical-return` accepts either absolute ISO dates with `--from`/`--to` or
+  a shorthand lookback with `--period`, such as `1y` or `6m`.
+- `beta` accepts `--years 1|3|5`.
+- `var --confidence` takes percentages such as `95` or `99`.
+- Use `--json` for machine parsing.

package/skills/quantbrasil/references/quality-eval-queries.json

@@ -0,0 +1,127 @@
+[
+  {
+    "query": "Qual foi o último preço da PETR4 no QuantBrasil?",
+    "should_trigger": true,
+    "expected_behavior": "Use quantbrasil market price PETR4 before generic web or finance search."
+  },
+  {
+    "query": "Mostra o preço e a análise técnica da VALE3.",
+    "should_trigger": true,
+    "expected_behavior": "Use assets overview with the price and technicals sections."
+  },
+  {
+    "query": "Quero preço, fundamentos e rankings de ITUB4.",
+    "should_trigger": true,
+    "expected_behavior": "Use assets overview with only valid sections: price,fundamentals,rankings."
+  },
+  {
+    "query": "Mostra valuation e resumo da PETR4 pela CLI.",
+    "should_trigger": true,
+    "expected_behavior": "Do not pass invalid sections like valuation or summary; inspect capabilities or explain the supported asset overview sections."
+  },
+  {
+    "query": "Crie uma watchlist chamada Dividendos e adicione PETR4 e VALE3.",
+    "should_trigger": true,
+    "expected_behavior": "Use watchlists create followed by watchlists add-assets with explicit tickers."
+  },
+  {
+    "query": "Atualize os pesos alvo da carteira Longo Prazo para PETR4 50 e VALE3 50.",
+    "should_trigger": true,
+    "expected_behavior": "Resolve the holding id if needed, then use holdings set-targets; do not use a generic portfolio command."
+  },
+  {
+    "query": "Liste minhas carteiras e calcule o retorno histórico da carteira Longo Prazo.",
+    "should_trigger": true,
+    "expected_behavior": "Use holdings list to resolve the saved holding, then holdings historical-return."
+  },
+  {
+    "query": "Qual é o beta da minha carteira contra o Ibovespa?",
+    "should_trigger": true,
+    "expected_behavior": "Use holdings beta for a saved holding; do not calculate beta for a watchlist."
+  },
+  {
+    "query": "Quais universos salvos eu posso usar no screening de indicadores?",
+    "should_trigger": true,
+    "expected_behavior": "Use screening universes and present system portfolios, watchlists, and holdings."
+  },
+  {
+    "query": "Quais indicadores posso usar no screening?",
+    "should_trigger": true,
+    "expected_behavior": "Use screening indicators and present supported indicator names, params, examples, timeframes, and operators."
+  },
+  {
+    "query": "Rode um screening de IFR na carteira do sistema Ações Mais Líquidas.",
+    "should_trigger": true,
+    "expected_behavior": "Use screening run with one explicit --system selector and a ScreenerRequest JSON payload."
+  },
+  {
+    "query": "A CLI retornou auth_failed quando tentei buscar PETR4.",
+    "should_trigger": true,
+    "expected_behavior": "Load error guidance; explain auth login or QUANTBRASIL_API_KEY without inspecting credential files."
+  },
+  {
+    "query": "A CLI disse rate_limited ao rodar várias métricas de carteira.",
+    "should_trigger": true,
+    "expected_behavior": "Load errors and costs guidance; avoid retry loops and recommend waiting or narrowing heavy calls."
+  },
+  {
+    "query": "Meu terminal diz quantbrasil: command not found.",
+    "should_trigger": true,
+    "expected_behavior": "Report that the CLI binary is not on PATH and ask the user to install it or fix PATH; do not inspect the repo."
+  },
+  {
+    "query": "Apague uma carteira salva da minha conta.",
+    "should_trigger": true,
+    "expected_behavior": "Load unsupported guidance and explain that deleting holdings is not public in the CLI."
+  },
+  {
+    "query": "Exporte uma resposta JSON grande para arquivo usando a CLI.",
+    "should_trigger": true,
+    "expected_behavior": "Load unsupported guidance and explain that --output file export is not public yet."
+  },
+  {
+    "query": "Rode um filtro com estes tickers avulsos: PETR4, VALE3 e BBAS3.",
+    "should_trigger": true,
+    "expected_behavior": "Load unsupported guidance; do not invent ad-hoc ticker-list screening."
+  },
+  {
+    "query": "What's the latest PETR4 price in QuantBrasil?",
+    "should_trigger": true,
+    "expected_behavior": "Use quantbrasil market price PETR4."
+  },
+  {
+    "query": "Show me the price and technical overview for VALE3.",
+    "should_trigger": true,
+    "expected_behavior": "Use assets overview with price and technicals sections."
+  },
+  {
+    "query": "Run a screen over these ad-hoc tickers: PETR4, VALE3, BBAS3.",
+    "should_trigger": true,
+    "expected_behavior": "Load unsupported guidance; do not invent ad-hoc ticker-list screening."
+  },
+  {
+    "query": "Implemente um novo comando na CLI dentro do repositório do QuantBrasil.",
+    "should_trigger": false,
+    "expected_behavior": "Handle as code implementation work, not as a market-data CLI usage task."
+  },
+  {
+    "query": "Revise este pull request procurando bugs no backend.",
+    "should_trigger": false,
+    "expected_behavior": "Handle as code review work, not as a QuantBrasil CLI data task."
+  },
+  {
+    "query": "Procure na web a cotação de hoje do dólar contra o real.",
+    "should_trigger": false,
+    "expected_behavior": "Use external lookup because the user explicitly requested the web and this is not a QuantBrasil-supported asset workflow."
+  },
+  {
+    "query": "Explique conceitualmente o que significa beta de uma carteira.",
+    "should_trigger": false,
+    "expected_behavior": "Answer conceptually; no CLI call is needed unless the user asks for a saved holding metric."
+  },
+  {
+    "query": "Monte uma planilha para meus gastos mensais.",
+    "should_trigger": false,
+    "expected_behavior": "Use spreadsheet/document workflow, not the QuantBrasil CLI skill."
+  }
+]

package/skills/quantbrasil/references/rankings.md

@@ -0,0 +1,62 @@
+# Rankings
+
+Use rankings for order-first questions: Magic Formula, momentum leaders,
+dividend-yield leaders, Momentum Double, or saved user rankings. A ranking
+returns an ordered asset list plus the metric used to order it.
+
+## Discovery
+
+Always discover ids before running a ranking unless the user already gave an
+exact id.
+
+```bash
+quantbrasil rankings list
+```
+
+The list is grouped into:
+
+- system rankings: platform-provided rankings selected by stable slugs
+- user rankings: saved rankings owned by the authenticated user
+
+## Current ranking
+
+System ranking:
+
+```bash
+quantbrasil rankings current --system momentum-90d --top 20
+quantbrasil rankings current --system magic-formula --top 10
+```
+
+User ranking:
+
+```bash
+quantbrasil rankings current --id 123 --top 20
+```
+
+Rules:
+
+- use exactly one selector: `--system` for system rankings or `--id` for user rankings
+- system rankings use slugs such as `momentum-90d` or `magic-formula`
+- user rankings use the numeric id shown under "Meus rankings"
+- `--top` is the number of ranked assets to return
+- use `--json` when another step needs to parse tickers, rank, score, or metric values
+- do not use `factor:<id>` in command syntax; ranking fatorial is a saved user ranking and uses `--id <id>`
+
+## Ranking vs screening
+
+Use rankings when the user starts from an ordered list:
+
+- "top 20 do momentum"
+- "top 10 Magic Formula"
+- "meu ranking de qualidade"
+- "ativos com maior dividend yield"
+
+Use screening when the user starts from a condition:
+
+- "IFR14 abaixo de 30"
+- "ativos sobrevendidos"
+- "preço acima da média móvel"
+
+If the user wants both ranking and a condition, keep the steps explicit. First
+get the ranking with `--json`, then apply the follow-up workflow only if the CLI
+surface supports that next step. Do not invent ranking-specific screening flags.

package/skills/quantbrasil/references/screening.md

@@ -0,0 +1,212 @@
+# Screening
+
+Use screening for indicator filters over saved QuantBrasil universes.
+
+## Discovery
+
+```bash
+quantbrasil screening universes
+quantbrasil screening indicators
+```
+
+Use `screening universes` to pick the asset set. The CLI supports only saved,
+portfolio-backed universes:
+
+- system portfolios via `--system <slug>`
+- watchlists via `--watchlist <id>`
+- holdings via `--holding <id>`
+
+Do not invent ad-hoc ticker-list screening. If the user gives loose tickers,
+explain that this CLI slice only screens saved universes.
+
+Use `screening indicators` before building JSON when the indicator name,
+parameters, timeframes, or comparison operators are unclear.
+
+## Common Portuguese mappings
+
+- `IFR`, `IFR14`, `IFR(14)` -> `RSI` with `params.period = 14`
+- `IFR2`, `IFR(2)` -> `RSI` with `params.period = 2`
+- `sobrevendido` usually means low RSI, commonly `< 30` or a threshold supplied by the user
+- `sobrecomprado` usually means high RSI, commonly `> 70` or a threshold supplied by the user
+- `Ações Mais Líquidas` -> system universe slug `acoes-mais-liquidas` when present in `screening universes`
+
+## Operators
+
+- `lt` means less than
+- `lte` means less than or equal to
+- `gt` means greater than
+- `gte` means greater than or equal to
+- `eq` means equal to
+- `neq` means not equal to
+
+## IFR14 abaixo de 25
+
+```json
+{
+  "query": {
+    "comparison": {
+      "left": {
+        "indicator": {
+          "name": "RSI",
+          "timeframe": "D1",
+          "offset": 0,
+          "params": {
+            "period": 14
+          }
+        }
+      },
+      "operator": "lt",
+      "right": {
+        "constant": {
+          "value": 25
+        }
+      }
+    }
+  },
+  "limit": 500,
+  "sort": "ticker"
+}
+```
+
+Run it:
+
+```bash
+quantbrasil screening run --system acoes-mais-liquidas --query-file ./screening-ifr14-lt-25.json
+```
+
+For agent/script parsing:
+
+```bash
+quantbrasil screening run --system acoes-mais-liquidas --query-file ./screening-ifr14-lt-25.json --json
+```
+
+## IFR14 acima de 70
+
+```json
+{
+  "query": {
+    "comparison": {
+      "left": {
+        "indicator": {
+          "name": "RSI",
+          "timeframe": "D1",
+          "offset": 0,
+          "params": {
+            "period": 14
+          }
+        }
+      },
+      "operator": "gt",
+      "right": {
+        "constant": {
+          "value": 70
+        }
+      }
+    }
+  },
+  "limit": 500,
+  "sort": "ticker"
+}
+```
+
+## IFR2 abaixo de 10
+
+```json
+{
+  "query": {
+    "comparison": {
+      "left": {
+        "indicator": {
+          "name": "RSI",
+          "timeframe": "D1",
+          "offset": 0,
+          "params": {
+            "period": 2
+          }
+        }
+      },
+      "operator": "lt",
+      "right": {
+        "constant": {
+          "value": 10
+        }
+      }
+    }
+  },
+  "limit": 500,
+  "sort": "ticker"
+}
+```
+
+## Exemplo com AND lógico
+
+Este exemplo filtra ativos com fechamento acima da média móvel de 20 períodos e
+IFR14 abaixo de 30.
+
+```json
+{
+  "query": {
+    "logical": {
+      "op": "AND",
+      "expressions": [
+        {
+          "comparison": {
+            "left": {
+              "indicator": {
+                "name": "OHLC",
+                "timeframe": "D1",
+                "offset": 0,
+                "params": {
+                  "price_type": "close"
+                }
+              }
+            },
+            "operator": "gt",
+            "right": {
+              "indicator": {
+                "name": "RollingWindow",
+                "timeframe": "D1",
+                "offset": 0,
+                "params": {
+                  "window": 20,
+                  "method": "mean"
+                }
+              }
+            }
+          }
+        },
+        {
+          "comparison": {
+            "left": {
+              "indicator": {
+                "name": "RSI",
+                "timeframe": "D1",
+                "offset": 0,
+                "params": {
+                  "period": 14
+                }
+              }
+            },
+            "operator": "lt",
+            "right": {
+              "constant": {
+                "value": 30
+              }
+            }
+          }
+        }
+      ]
+    }
+  },
+  "limit": 100,
+  "sort": "ticker"
+}
+```
+
+## Stdin
+
+Use stdin when creating the JSON dynamically:
+
+```bash
+cat ./screening-ifr14-lt-25.json | quantbrasil screening run --system acoes-mais-liquidas --query-file -
+```

package/skills/quantbrasil/references/unsupported.md

@@ -3,12 +3,16 @@
 Unsupported in the public CLI:
 
 - `--output <file>` response export
+- deleting watchlists or holdings
+- value-based position input for traded assets
+- ad-hoc ticker-list screening
 
 Not a supported pattern:
 
 - inventing commands not shown in `quantbrasil --help`
 - assuming hidden flags exist
 - treating backend internals as public CLI contract
+- treating a watchlist as an investable composition for metrics
 
 Use the public surface only:
 
@@ -16,5 +20,6 @@ Use the public surface only:
 - `capabilities`
 - `market`
 - `assets`
-- `portfolios`
-- `analytics`
+- `screening`
+- `watchlists`
+- `holdings`