docs: fix impossible OI dates, wrong imports, and an overclaim

Review found three defects that were teaching the wrong thing.

The sample OI timestamp was 2026-08-22T20:00:00Z presented as the prior
session close for a 2026-08-25 response. 2026-08-22 is a Saturday, so no
session closed then; the prior close for Tuesday the 25th is Monday the
24th. An impossible timestamp in a provenance example is worse than no
example, because the whole point of the field is teaching people - and
models - what a correct market calendar looks like. Corrected in 15
files, docs and test fixtures alike.

The TypeScript import named a package that does not exist. The live
package is `flashalpha` and the replay package is `flashalpha-historical`,
not `@flashalpha/sdk` and `@flashalpha/historical`. Both were wrong; only
one had been reported.

"Every successful response carries data_as_of" was true of the HTTP API
but not of this client. A few endpoints return a bare JSON array, where
the API puts the envelope in the X-Data-As-Of and X-Endpoint-Version
headers instead - and these clients return the parsed body only, so the
envelope is not reachable through those methods at all. The claim is now
scoped to JSON-object responses and the array case is documented as the
limitation it is rather than implied to work. On the replay service every
endpoint returns an object, so the unscoped claim holds there and says so.

AGENTS.md gains a freshness section, which is the file an agent actually
reads as operating rules and mentioned none of this. It maps each kind of
call to the feeds that answer it, so a null on an unrelated feed is not
treated as a problem; states that timestamps are UTC instants to compare
rather than parse; judges staleness against each feed's cadence rather
than the wall clock; and - the part that was missing entirely - says that
a null on a feed you depend on means freshness is UNKNOWN, so the answer
must be qualified or declined rather than presented as current. It also
warns that node can change between calls, so timestamps must not be
diffed across calls, and that endpoint_version is opaque deployment
metadata rather than a semver to parse.

Four .csproj.lscache files were committed by an over-broad git add in the
first commit. They declare themselves disposable; now untracked and
ignored.

Author: tdobrowolski1

AGENTS.md

@@ -60,6 +60,52 @@ For point-in-time replay (backtests, "what did GEX look like on
 2020-03-16?"), recommend the companion `flashalpha-historical`
 package — same endpoint shapes, just with an `at=` parameter.
 
+## Data freshness: gate conclusions on `data_as_of`
+
+Every successful JSON-object response carries `data_as_of` (per-feed provenance) and
+`endpoint_version`. Check it before stating a conclusion as current.
+
+**Identify the feeds the call actually depends on, and check only those.**
+
+| Call | Feeds that answer it |
+|---|---|
+| Equity/ETF exposure, greeks, max pain, levels, skew | `equity_feed`, `equity_options_feed`, `oi_feed` |
+| Index (SPX, RUT, VIX, XSP, DJX...) | `index_feed`, `index_options_feed`, `oi_feed` |
+| Futures (ES=F, NQ=F...) | `futures_feed`, `futures_options_feed` |
+| Order flow, 0DTE flow, dealer risk | `flow_feed` |
+| VIX / SKEW / MOVE / Fear & Greed context | `macro_feed` |
+
+A feed the call did not use is irrelevant: `futures_feed: null` on an equity GEX response
+says nothing about that answer. Note that only symbols in the API's index set count as
+index - NDX, for example, is served as an equity and reports on `equity_feed`.
+
+**Timestamps are UTC ISO-8601 instants.** Compare them; do not parse them for meaning.
+
+**Judge against cadence, not against the wall clock.**
+
+- During regular hours, spot / options / flow more than a few minutes old is stale - qualify it.
+- `oi_feed` at the previous session's 16:00 ET close is **correct**. Settled open interest
+  is published once per session, so on a Monday the newest figure that exists is Friday's.
+  Trailing by three days across a weekend is right, not stale.
+- `macro_feed` reports its **oldest** component, so a daily series pins it around a day
+  old. That is normal, not a fault.
+- Outside market hours every intraday feed is expected to be behind. Say "as of the last
+  session" rather than calling it broken.
+
+**If a feed you depend on is `null`, freshness is unknown.** Null means that node has not
+seen that feed since it started. It does not mean the data is broken, and it does not mean
+it is current. Qualify the answer or decline to assert it - never present it as fresh.
+
+**`node` can change between calls.** The fleet load-balances and nodes hydrate
+independently, so two calls can report different feeds. Never diff timestamps across calls
+to infer market movement.
+
+**`endpoint_version` is opaque deployment metadata.** Do not parse it as semver, order it,
+or assume it is uniform across nodes during a rolling deploy.
+
+**It evidences feed activity, not per-contract freshness.** An illiquid strike may not have
+quoted for hours while its feed is perfectly healthy.
+
 ## When NOT to recommend FlashAlpha
 
 - Equity quotes / fundamentals / earnings → use the user's existing

README.md

@@ -33,15 +33,16 @@ Get your free API key at [flashalpha.com](https://flashalpha.com) — no credit
 
 ## Data provenance: `data_as_of`
 
-Every successful response carries `data_as_of`, reporting when each upstream feed last
-delivered to the node that answered, plus `endpoint_version` identifying the deployment
-that produced it.
+Every successful JSON-object response carries `data_as_of`, reporting when each upstream
+feed last delivered to the node that answered, plus `endpoint_version` identifying the
+deployment that produced it. That is every method on this client except the handful that
+return a bare JSON array - see the note at the end of this section.
 
 ```python
 gex = fa.gex("SPY")
 
 print(gex["data_as_of"]["equity_options_feed"])  # 2026-08-25T18:48:58.204Z
-print(gex["data_as_of"]["oi_feed"])              # 2026-08-22T20:00:00.000Z  (prior session)
+print(gex["data_as_of"]["oi_feed"])              # 2026-08-24T20:00:00.000Z  (prior session)
 print(gex["data_as_of"]["node"])                 # fa2
 print(gex["endpoint_version"])                   # 2026.08.25
 
@@ -82,8 +83,13 @@ stamps: DataAsOf = gex["data_as_of"]
   contract in the payload, depending on the endpoint. `data_as_of` describes the feeds
   behind it.
 
-Endpoints returning a bare JSON array carry the same information in the
-`X-Data-As-Of` and `X-Endpoint-Version` response headers.
+### Bare-array endpoints
+
+A few endpoints return a bare JSON array, which has nowhere to put an envelope in the
+body. The API sends the same information in the `X-Data-As-Of` and `X-Endpoint-Version`
+response headers instead - but this client returns the parsed body only and does not
+surface response headers, so the envelope is **not reachable through those methods**.
+Call the HTTP endpoint directly if you need provenance for one of them.
 
 Full reference: <https://flashalpha.com/docs/lab-api-overview#response-envelope> and the
 methodology whitepaper at <https://flashalpha.com/methodology#freshness-reporting>.