@quantbrasil/cli 0.1.0-beta.0

package/skills/quantbrasil/references/cli.md

@@ -0,0 +1,77 @@
+# CLI Reference
+
+## Readiness and auth
+
+```bash
+quantbrasil --status
+quantbrasil auth login --api-key <key>
+quantbrasil auth logout
+quantbrasil capabilities --json
+quantbrasil init
+```
+
+## Market
+
+```bash
+quantbrasil market assets
+quantbrasil market assets --type B3
+quantbrasil market assets --json
+
+quantbrasil market price PETR4
+quantbrasil market price PETR4 --date 2026-04-10
+quantbrasil market price PETR4 --timeframe W1
+quantbrasil market price PETR4 --json
+```
+
+## Asset analysis
+
+```bash
+quantbrasil assets overview PETR4 --sections price,performance
+quantbrasil assets overview PETR4 --sections price,technicals
+quantbrasil assets overview PETR4 --sections price,fundamentals --json
+```
+
+Valid `--sections`:
+
+- `price`
+- `performance`
+- `momentum`
+- `technicals`
+- `risk`
+- `fundamentals`
+- `rankings`
+
+## Portfolios
+
+```bash
+quantbrasil portfolios list
+quantbrasil portfolios list --json
+
+quantbrasil portfolios get 93
+quantbrasil portfolios get 93 --json
+
+quantbrasil portfolios create "Dividendos"
+quantbrasil portfolios rename 93 "Longo Prazo"
+quantbrasil portfolios add-assets 93 PETR4 VALE3
+quantbrasil portfolios remove-assets 93 PETR4
+```
+
+## Analytics
+
+Saved portfolio:
+
+```bash
+quantbrasil analytics historical-return --portfolio 93 --from 2025-01-01 --to 2026-01-01
+quantbrasil analytics beta --portfolio 93 --years 1
+quantbrasil analytics var --portfolio 93 --years 1 --confidence 95
+```
+
+Ad-hoc basket:
+
+```bash
+quantbrasil analytics historical-return --asset VALE3:50 --asset PRIO3:50 --from 2025-01-01 --to 2026-01-01
+quantbrasil analytics beta --asset VALE3:50 --asset PRIO3:50 --years 3
+quantbrasil analytics var --asset VALE3:120 --asset WINFUT:-20 --years 1 --confidence 99
+```
+
+Use `--json` on any analytics command when machine parsing needed.

package/skills/quantbrasil/references/costs.md

@@ -0,0 +1,30 @@
+# Cost-Aware Behavior
+
+Exact public credit pricing is not locked yet.
+
+Current guidance uses backend qualitative classes only:
+
+- `free`
+- `standard`
+- `heavy`
+
+## Current behavior guidance
+
+- `market assets` is lowest-cost discovery path
+- `market price` is narrow read path
+- `assets overview` is richer and should use minimal `--sections`
+- portfolio analytics (`historical-return`, `beta`, `var`) are heaviest current public reads
+
+## Agent rules
+
+- prefer narrow command that answers question
+- prefer `market price` over `assets overview` for quote-only requests
+- prefer one analytics call targeted to actual question
+- do not chain multiple heavy analytics calls unless user asked for them
+- use `--json` only when structured output needed
+
+## Safe defaults
+
+- discover portfolio id once, then reuse it
+- avoid full-report behavior when user asked only one metric
+- keep `assets overview --sections` minimal and relevant

package/skills/quantbrasil/references/errors.md

@@ -0,0 +1,128 @@
+# Error Handling
+
+## Auth / readiness
+
+Check:
+
+```bash
+quantbrasil --status
+```
+
+If not ready:
+
+```bash
+quantbrasil auth login --api-key <key>
+```
+
+If local backend or staging needed:
+
+```bash
+QB_BACKEND_URL=http://127.0.0.1:8000 quantbrasil --status
+```
+
+## Validation failures
+
+Treat CLI validation as user-input error.
+
+Examples:
+
+- invalid portfolio id
+- invalid `--sections`
+- invalid `--asset TICKER[:WEIGHT_PCT]`
+- invalid `--years`
+
+Fix input. Do not retry same bad command.
+
+Stable code:
+
+- `validation_error`
+
+## Backend auth failures
+
+Typical causes:
+
+- bad API key
+- revoked API key
+- wrong backend target
+
+Recovery:
+
+1. run `quantbrasil --status`
+2. re-login if needed
+3. confirm `QB_BACKEND_URL` target
+
+Stable codes:
+
+- `auth_required`
+- `auth_failed`
+
+## Not found / empty data
+
+Possible causes:
+
+- portfolio id does not exist
+- ticker not tracked
+- requested history unavailable for period
+
+Recovery:
+
+- use `market assets` for discovery
+- use `portfolios list` before `portfolios get`
+- narrow period or pick another ticker
+
+Stable code:
+
+- `not_found`
+
+## Rate limits
+
+Do not retry immediately in a tight loop.
+
+Recovery:
+
+- wait before retrying
+- reduce repeated calls
+- reuse data already returned by a previous command
+
+Stable code:
+
+- `rate_limited`
+
+## Mutation failures
+
+Mutation commands can fail even when the backend route is reachable, for example
+when a requested ticker is invalid for the operation.
+
+Recovery:
+
+- read the error message
+- fix the requested portfolio id, name, ticker list, or operation
+- do not retry unchanged mutation input
+
+Stable code:
+
+- `mutation_failed`
+
+## Machine handling note
+
+For commands that expose `--json`, failures are written to stderr as:
+
+```json
+{
+  "ok": false,
+  "error": {
+    "code": "validation_error",
+    "message": "Invalid section \"summary\". Use only: price, performance, momentum, technicals, risk, fundamentals, rankings.",
+    "category": "validation",
+    "exit_code": 1
+  }
+}
+```
+
+Human stderr includes the same stable code, for example:
+
+```text
+[validation_error] Invalid section "summary". Use only: price, performance, momentum, technicals, risk, fundamentals, rankings.
+```
+
+Branch on `error.code`, not full message text.

package/skills/quantbrasil/references/unsupported.md

@@ -0,0 +1,20 @@
+# Unsupported
+
+Unsupported in the public CLI:
+
+- `--output <file>` response export
+
+Not a supported pattern:
+
+- inventing commands not shown in `quantbrasil --help`
+- assuming hidden flags exist
+- treating backend internals as public CLI contract
+
+Use the public surface only:
+
+- `auth`
+- `capabilities`
+- `market`
+- `assets`
+- `portfolios`
+- `analytics`

package/skills/quantbrasil/references/workflows.md

@@ -0,0 +1,99 @@
+# Workflows
+
+## Find supported ticker, then get price
+
+Use this when user gives company theme, partial name, or market universe question.
+
+```bash
+quantbrasil market assets --type B3
+quantbrasil market price PETR4
+```
+
+If exact ticker already known, skip discovery and go straight to `market price`.
+
+## Get price on specific date
+
+```bash
+quantbrasil market price PETR4 --date 2026-04-10
+```
+
+Use absolute ISO dates.
+
+## Pick cheapest asset command first
+
+- need only current or dated quote → `market price`
+- need tracked universe / supported symbols → `market assets`
+- need richer analysis for one asset → `assets overview`
+
+Do not jump to `assets overview` if price-only answer is enough.
+
+## Cost-aware `assets overview` section choice
+
+Keep `--sections` minimal.
+
+Good:
+
+```bash
+quantbrasil assets overview PETR4 --sections price,performance
+quantbrasil assets overview PETR4 --sections price,technicals
+quantbrasil assets overview PETR4 --sections risk,fundamentals
+```
+
+Guidance:
+
+- `price,performance` for quick market context
+- `technicals,momentum` for chart / signal questions
+- `risk` for drawdown / volatility style questions
+- `fundamentals,rankings` for valuation / ranking context
+
+Avoid asking for every section unless user clearly wants full report.
+
+## Analyze saved portfolio
+
+1. Discover portfolio id.
+2. Inspect holdings if needed.
+3. Run analytics.
+
+```bash
+quantbrasil portfolios list
+quantbrasil portfolios get 93
+quantbrasil analytics historical-return --portfolio 93 --from 2025-01-01 --to 2026-01-01
+quantbrasil analytics beta --portfolio 93 --years 1
+quantbrasil analytics var --portfolio 93 --years 1 --confidence 95
+```
+
+## Analyze ad-hoc basket
+
+Use repeated `--asset TICKER[:WEIGHT_PCT]`.
+
+Rules:
+
+- if weights omitted, backend may assume equal weights
+- negative weights allowed for hedge / short exposure
+- `beta` only accepts `--years 1|3|5`
+- `var --confidence` takes percent like `95` or `99`
+
+Example:
+
+```bash
+quantbrasil analytics historical-return --asset VALE3:50 --asset PRIO3:50 --from 2025-01-01 --to 2026-01-01
+quantbrasil analytics beta --asset VALE3:120 --asset WINFUT:-20 --years 1
+quantbrasil analytics var --asset VALE3:120 --asset WINFUT:-20 --years 1 --confidence 99
+```
+
+## Modify saved portfolio
+
+Use explicit mutation commands. Do not retry failed mutations automatically.
+
+```bash
+quantbrasil portfolios create "Dividendos"
+quantbrasil portfolios rename 93 "Longo Prazo"
+quantbrasil portfolios add-assets 93 PETR4 VALE3
+quantbrasil portfolios remove-assets 93 PETR4
+```
+
+Rules:
+
+- use `portfolios list` first if user names a portfolio instead of giving id
+- confirm destructive intent before removing assets when user request is ambiguous
+- use `--json` only when structured output is needed