# GrainBud AI Portfolio Skill

GrainBud is a private read-only investment portfolio API. It is a neutral data provider for the user's current confirmed holdings, reference quotes, FX estimates, account freshness, source lineage, and data-quality or exposure diagnostics. GrainBud does not provide portfolio advice or trading recommendations; downstream AI tools may analyze the data independently, but should not attribute their conclusions to GrainBud.

## Endpoint

- Hosted skill file: `https://grainbud.poorlow.com/skill.md`
- Single-link AI brief: `https://grainbud.poorlow.com/agent.md`
- AI crawler index: `https://grainbud.poorlow.com/llms.txt`
- Portfolio snapshot: `https://grainbud.poorlow.com/api/ai/portfolio/snapshot`
- Positions query: `https://grainbud.poorlow.com/api/ai/positions`
- Known instrument search: `https://grainbud.poorlow.com/api/ai/instruments/search?q=<code-or-name>`
- Latest reference quote: `https://grainbud.poorlow.com/api/ai/quotes/latest?symbol=<code>`
- Fund intraday estimate: `https://grainbud.poorlow.com/api/ai/funds/intraday-estimates?code=<fund-code>`
- Exposures: `https://grainbud.poorlow.com/api/ai/exposures`
- Data quality: `https://grainbud.poorlow.com/api/ai/data-quality`
- OpenAPI contract: `https://grainbud.poorlow.com/api/ai/openapi`
- Required scope when auth is enabled: `portfolio:snapshot:read`

## Authentication

Authentication required: no

Preferred form:

```bash
curl -H "Authorization: Bearer <token>" "https://grainbud.poorlow.com/api/ai/portfolio/snapshot"
```

Alternative header:

```bash
curl -H "x-api-token: <token>" "https://grainbud.poorlow.com/api/ai/portfolio/snapshot"
```

If authentication is disabled, call the snapshot URL directly.

## Reader Compatibility

- Prefer a web/page reader, browser fetch tool, OpenAPI tool, or direct HTTP fetch capability for these URLs.
- Do not rely on hosted Python/code-interpreter requests as the primary fetch path. Some AI code sandboxes have restricted DNS or outbound internet and can raise temporary `NameResolutionError` failures even when GrainBud is publicly reachable.
- If a Python `requests` call fails with DNS or temporary name-resolution errors, treat that as a sandbox/network limitation and retry with the web reader or direct URL tools before judging endpoint health.

## Interpretation Rules

1. Treat confirmed snapshot values as the authoritative account facts.
2. Treat `quote_price`, fund NAV, delayed quotes, FX conversions, `external_estimated_value`, and `reference_value` as neutral reference market data. They do not overwrite confirmed account facts.
3. Always inspect `/api/ai/data-quality` or `snapshot.data_freshness`, `snapshot.refresh_recommendations`, `snapshot.pre_advice_disclosures`, and `snapshot.diagnostics.flags` before using the data. Treat `diagnostics.flags` as data-quality or exposure diagnostics, not GrainBud recommendations.
4. Do not infer trades, cash transfers, cost basis, or account changes that are not present in the response.
5. Do not attempt to place orders, cancel orders, modify orders, unlock trading, or request trading credentials. This API is read-only.
6. GrainBud does not provide buy/sell/hold recommendations, rebalancing instructions, stop-loss/take-profit levels, recovery plans, or cash-planning judgments.
7. Downstream AI tools may independently analyze these data fields, but recommendations or conclusions must not be attributed to GrainBud.
8. Never promise recovery, guaranteed return, or certain future prices. Never present reference quotes as live executable broker quotes.

## Suggested AI Workflow

1. Install or read `/skill.md` for this workflow, then fetch `/api/ai/manifest` if machine-readable discovery is available.
2. Call `/api/ai/data-quality` before using the data. If refresh_recommendations.status is not clear, disclose the caveat.
3. Call `/api/ai/portfolio/snapshot` for full facts, `/api/ai/positions` for filtered holdings, and `/api/ai/exposures` for theme or classification exposure.
4. To answer "what is the latest price for this held stock/fund/gold product", call `/api/ai/quotes/latest?symbol=<code>`. It returns the latest stored reference quote for known GrainBud instruments only.
5. To answer "what is the current intraday estimate for a synced open-end fund", call `/api/ai/funds/intraday-estimates?code=<fund-code>`. Treat it as reference-only estimated NAV data, not official confirmed NAV.
6. For quote-aware downstream analysis, use `quotes/latest` or `funds/intraday-estimates` for the specific instrument, then cross-check the full snapshot for position size, account weight, reference value, concentration, and freshness.
7. Clearly separate confirmed facts from reference estimates, and do not present downstream judgments as GrainBud guidance.