# FlowDensity Agent Skill

Use this skill when an agent, bot, or Decision Terminal connector consumes
FlowDensity. FlowDensity is a market positioning pressure instrument. It emits
derived KPI packets and cited reads. It never trades, predicts direction, sizes
positions, routes orders, or redistributes raw vendor data.

Family objectivity rule: numbers carry no opinion, and opinions carry no
number. Treat scores, KPIs, rankings, gauges, and calibration metrics as
measurements only. Treat Pressure Reads and Insight Objects as cited content
only; never convert them into a score, rank, Signal Field, or trade view.

## Required Sequence

1. Fetch `GET /v1/schema`.
2. Read `api_scope`, `objectivity_doctrine`, `decision_terminal_identity`,
   `agent_native`, `data_policy`, `packet_shapes`, and `planned_contracts`.
3. For planned flow contracts, preserve
   `quality_gate_contract.required_fields`,
   `quality_gate_contract.required_context_fields`, and
   `quality_gate_contract.context_field_policy`. Treat source fields as
   internal eligibility gates and context fields as authorized normalization
   inputs, not public event payloads or redistribution rights.
4. Fetch `GET /v1/core-kpis` and preserve `catalog_fingerprint`,
   `missing_policy`, `fields`, and each KPI's `objectivity_status`.
5. Fetch `GET /v1/board` and treat each row as a public pressure packet.
6. Fetch `GET /v1/assets/{symbol}` only when a board row needs inspection.
7. Fetch `GET /v1/watchlist` when configured symbol coverage matters. Treat
   personalization and notice delivery as `not_built`, never as active delivery.
8. Fetch `GET /v1/replay/state-changes` only when state-change replay or future
   push delivery context matters. Treat `delivery.status: not_configured` as no
   active delivery channel.
9. Fetch `GET /v1/scorecard` when public calibration readiness matters
   (`/v1/calibration/scorecard` remains a compatibility path). Fetch
   `GET /v1/scorecard/methodology` when the CP-072 gate contract matters.
   Preserve the pressure-spine readouts (`event_risk_scorecard`,
   `volume_pressure_scorecard`, `squeeze_risk_scorecard`,
   `flow_divergence_scorecard`, and `positioning_pressure_scorecard`) when
   deciding whether any FD sleeve has evidence against forward absolute
   movement. Treat `metrics: null` as blocked, never as zero.
10. Fetch `GET /v1/reads/board` or `GET /v1/reads/{symbol}` only after the
   packet fields are loaded. Render read text only with its `fields_cited`.
11. Fetch `GET /v1/insights/board` or `GET /v1/insights/{symbol}` when an
   agent-native handoff needs `insight_object_v0`.
12. Fetch `GET /health/deep` when freshness, provider, or store status matters.

## Identity

Use the public packet join key exactly as schema reports it:

```text
(instrument_id, symbol, as_of, window)
```

Join on `instrument_id`, never the ticker string alone — tickers can change;
`instrument_id` survives renames.
`asset` is a backward-compatible alias for `symbol`. Do not treat it as a
second identifier. v0.1 public packets use `window: "1d"`.

## Preserve

Every client must preserve:

- `instrument_id`
- `symbol`
- `window`
- `as_of`
- `score: null`
- `gaps[]`
- `freshness`
- `confidence`
- `confidence_cap_reason`
- `planned_contracts[].quality_gate_contract.required_fields`
- `planned_contracts[].quality_gate_contract.required_context_fields`
- `planned_contracts[].quality_gate_contract.context_field_policy`
- `core_kpis.catalog_fingerprint`
- `next_catalyst.confirmed`
- `data_policy`
- `calibration_scorecard.publishable`
- `calibration_scorecard.blocked_reason`
- `calibration_scorecard.event_risk_scorecard.scorecard_outcome_metric_basis`
- `calibration_scorecard.volume_pressure_scorecard.scorecard_outcome_metric_basis`
- `calibration_scorecard.squeeze_risk_scorecard.scorecard_outcome_metric_basis`
- `calibration_scorecard.flow_divergence_scorecard.scorecard_outcome_metric_basis`
- `calibration_scorecard.flow_divergence_scorecard.forward_return_relationship_gate`
- `calibration_scorecard.positioning_pressure_scorecard.scorecard_outcome_metric_basis`
- `state_change_replay.delivery.status`
- `watchlist.personalization.status`
- `watchlist.notice_delivery.status`
- `fields_cited`
- `insight_object_v0` fields when using `/v1/insights/*`

Unknown stays unknown. Never coerce a missing score to zero, fifty, quiet, or
neutral.

## Allowed Agent Work

Agents may:

- rank watched assets by `pressure_score` while keeping nulls last and visible;
- explain which sleeve owns `primary_signal`;
- explain why confidence is capped from `confidence_cap_reason`;
- attach the catalyst clock from `next_catalyst`;
- report configured watchlist symbols from `/v1/watchlist`;
- report state-change replay delivery readiness from
  `/v1/replay/state-changes`;
- report the public KPI field catalog from `/v1/core-kpis` without converting
  labels into opinions;
- report calibration scorecard readiness from `/v1/scorecard`;
- report the CP-072 methodology contract from `/v1/scorecard/methodology`;
- report pressure-spine scorecard readiness for `fd.event_risk`,
  `fd.volume_pressure`, `fd.squeeze_risk`, `fd.flow_divergence`, and
  `fd.positioning_pressure` against `forward_abs_move_pct` from their matching
  `calibration_scorecard.*_scorecard` readouts, including pending outcomes and
  blocked gates;
- quote exact packet paths from `fields_cited`;
- explain that `market_cap` is authorized context for `premium_per_mcap` and
  `notional_per_mcap` when planned flow contracts are blocked or inspected;
- hand off `insight_object_v0` without adding claims, uncited fields, or
  numeric opinions;
- compare FlowDensity's money-pressure state with sister-feed context when that
  context is separately provided.

## Prohibited Agent Work

Agents must not:

- recommend entries, exits, position size, hedges, routes, or timing;
- predict price direction, future returns, or probabilities;
- convert pressure into urgency, hype, conviction, or ROI language;
- convert Pressure Reads, Insight Objects, Deep Dives, AI overlays, commentary,
  or narrative interpretation into a score, rank, KPI, gauge, or Signal Field;
- create entry-quality, setup-quality, foundation, polarity, urgency,
  conviction, narrative-impact, ROI, or trade-edge numbers;
- treat blocked scorecard metrics as zero, directional accuracy, ROI, or trade
  edge;
- infer quiet activity from blocked flow, missing IV, absent events, or null
  scores;
- claim an unconfirmed catalyst is confirmed;
- treat configured watchlist symbols as personal holdings, user intent, active
  notice delivery, or permission to notify;
- expose raw options chains, raw sweep or block tapes, raw dark-pool prints,
  raw vendor payloads, or raw social posts;
- treat required source fields as public payload fields or data rights;
- treat `required_context_fields` such as `market_cap` as raw event tape,
  account state, or a trade input;
- treat `planned_contracts` as live data.

## Safe Response Pattern

When explaining a packet, use this structure:

1. State the measured pressure and freshness.
2. Name the primary signal and confidence cap, if any.
3. State the nearest catalyst and whether it is confirmed.
4. List gaps that limit the reading.
5. Stop before advice, direction, or action language.

Example:

```text
NVDA shows elevated event-risk pressure on the 1d window. The score is degraded
because IV magnitude is unavailable, so confidence is capped. The next catalyst
is a confirmed earnings date in 10 days. Treat the missing IV sleeve as a visible
gap, not as quiet activity.
```