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

package/skills/quantbrasil/references/rankings.md

@@ -1,8 +1,10 @@
 # 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.
+dividend-yield leaders, Low Risk, Momentum Double, or saved user rankings. A
+ranking returns an ordered asset list plus the metric used to order it.
+Use ranking return when the question asks how a ranking-based strategy performed
+over a historical period with rebalancing.
 
 ## Discovery
 
@@ -25,6 +27,7 @@ System ranking:
 ```bash
 quantbrasil rankings current --system momentum-90d --top 20
 quantbrasil rankings current --system magic-formula --top 10
+quantbrasil rankings current --system low-risk --top 30
 ```
 
 User ranking:
@@ -36,18 +39,43 @@ 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`
+- system rankings use slugs such as `momentum-90d`, `magic-formula`, or `low-risk`
 - 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 return
+
+Use this when the user asks how much a ranking strategy returned over time,
+such as Magic Formula top 20 rebalanced quarterly.
+
+```bash
+quantbrasil rankings return --system magic-formula --from 2024-01-18 --to 2026-05-25 --top 20 --rebalance quarterly
+quantbrasil rankings return --system momentum-90d --from 2024-01-01 --to 2026-01-01 --top 10 --rebalance monthly
+```
+
+Rules:
+
+- use `rankings list` first when the system slug or return support is unclear
+- `return` accepts `--system` only
+- `--from` and `--to` are required explicit ISO dates
+- do not use `--id`; saved user rankings do not support historical return in the public CLI
+- do not use `--period`; ranking return requires explicit dates
+- supported rebalance values are `weekly`, `monthly`, `bimonthly`, `quarterly`, `semiannually`, and `annually`
+- supported weighting is `equal`
+- `--index-filter` accepts `NONE`, `IBOV`, `IBX100`, or `SMLL`
+- system rankings with return support currently include Magic Formula, Dividend Yield, Momentum, and Momentum Double
+- Low Risk can be queried with `rankings current`, but does not support `rankings return`
+- use `--json` when another step needs rebalance portfolios or period-level returns
+
 ## Ranking vs screening
 
 Use rankings when the user starts from an ordered list:
 
 - "top 20 do momentum"
 - "top 10 Magic Formula"
+- "top 30 Low Risk"
 - "meu ranking de qualidade"
 - "ativos com maior dividend yield"
 

package/skills/quantbrasil/references/unsupported.md

@@ -6,6 +6,7 @@ Unsupported in the public CLI:
 - deleting watchlists or holdings
 - value-based position input for traded assets
 - ad-hoc ticker-list screening
+- scanning all cointegrated pairs in a universe
 
 Not a supported pattern:
 
@@ -20,6 +21,7 @@ Use the public surface only:
 - `capabilities`
 - `market`
 - `assets`
+- `cointegration`
 - `screening`
 - `watchlists`
 - `holdings`

package/skills/quantbrasil/references/workflows.md

@@ -5,11 +5,13 @@
 - asset price, quote, or daily move → `market price`
 - supported assets, tickers, or market universe → `market assets`
 - asset performance, technicals, risk, fundamentals, or ranking → `assets overview`
-- current ordered asset lists such as Magic Formula, momentum, or user rankings → `rankings list`, then `rankings current`
+- current ordered asset lists such as Magic Formula, momentum, Low Risk, or user rankings → `rankings list`, then `rankings current`
+- historical return of ranking strategies such as Magic Formula or Momentum → `rankings list`, then `rankings return`
 - watchlist details or changes → `watchlists ...`
 - holding details or changes → `holdings ...`
 - holding return, beta, risk, VaR, or comparison → `holdings historical-return|beta|var`
 - indicator screening over saved asset sets → `screening universes`, `screening indicators` when needed, then `screening run`
+- cointegration or Long & Short between two explicit assets → `cointegration pair`
 
 ## Find supported ticker, then get price
 
@@ -66,14 +68,16 @@ Avoid asking for every section unless user clearly wants full report.
 ## Get current ranked assets
 
 Use this when the user asks for an ordered list such as top Magic Formula,
-momentum leaders, dividend-yield leaders, Momentum Double, or a saved user
-ranking.
+momentum leaders, dividend-yield leaders, Low Risk, Momentum Double, or a saved
+user ranking.
 
 ```bash
 quantbrasil rankings list
 quantbrasil rankings current --system momentum-90d --top 20
 quantbrasil rankings current --system magic-formula --top 10
+quantbrasil rankings current --system low-risk --top 30
 quantbrasil rankings current --id 123 --top 20
+quantbrasil rankings return --system magic-formula --from 2024-01-18 --to 2026-05-25 --top 20 --rebalance quarterly
 ```
 
 Rules:
@@ -83,6 +87,9 @@ Rules:
 - user rankings use their numeric id from `rankings list`
 - use exactly one selector: `--system <slug>` or `--id <id>`
 - do not call user rankings "factor:" in command syntax; ranking fatorial is a saved user ranking
+- use `rankings return` for supported system rankings when the user asks historical return with rebalancing
+- `rankings return` requires explicit `--from` and `--to` dates and does not accept user ranking ids
+- Low Risk supports current ranking lookup, but not return simulation
 - use `--json` if another step needs to parse tickers, ranks, or ordering metrics
 - do not route ranking-first questions through screening unless the user asks for indicator conditions
 
@@ -123,6 +130,26 @@ Rules:
 - load `references/screening.md` for IFR/RSI examples and full JSON payloads
 - use `--json` when the result will be parsed by an agent or script
 
+## Run pair cointegration / Long & Short
+
+Use this when the user asks to run cointegração, cointegration, Long & Short,
+long and short, long-short, pair trading statistics, z-score, p-value, or
+half-life for two explicit assets.
+
+```bash
+quantbrasil cointegration pair PETR4 VALE3
+quantbrasil cointegration pair PETR4 VALE3 --window 120
+quantbrasil cointegration pair PETR4 VALE3 --json
+```
+
+Rules:
+
+- require two explicit tickers
+- frame Long & Short phrasing as pair analysis, not order execution or a guaranteed trade recommendation
+- use `market assets --search` first only if a ticker is ambiguous
+- do not invent a universe scan command for "quais pares cointegrados"; the public CLI currently supports explicit pairs
+- use `--json` if the z-score or beta series will feed another calculation
+
 ## Analyze a theoretical composition
 
 Create a holding with target weights, then run holding metrics on its id.