README GitHub Description Refresh

Summary

Refined the README overview and added a new section describing the live classification pipeline: ingest, parent-event reconstruction, evidence feature extraction, multi-profile scoring, and explainable output artifacts.

Changes Made

• Kept the heading image untouched at the top of README.md.
• Rewrote the opening capability bullets to match current architecture and app surfaces.
• Added a short current-state paragraph describing the event-sourced intelligence flow across NATS/JetStream and ClickHouse.
• Added How Print Classification Works (Current Approach), aligned to smartmoney.md and current compute behavior.
• Documented key behavior: abstention, suppression guards, and compatibility surfaces.

Context

The prior README already contained significant platform detail but needed a more GitHub-friendly “what this app is now” description and a direct explanation of print classification logic, especially the taxonomy-first approach instead of a binary smart-money label.

Important Implementation Details

• Classification language intentionally tracks the current compute path and event types: FlowPacket, SmartMoneyEvent, ClassifierHitEvent, and AlertEvent.
• The new section references smartmoney.md for conceptual grounding while staying concise enough for README readers.
• No API contracts or runtime logic changed; this is a documentation-only update.

Relevant Diff Snippets

Snippets below follow standard unified diff formatting as used by tools such as diffs.com.

- Islandflow is a Bun + TypeScript monorepo for a personal-use, event-sourced market microstructure research platform focused on:
- - options prints + NBBO,
- - off-exchange equity prints,
- - market news context,
- - explainable smart-money flow classification,
+ Islandflow is a Bun + TypeScript monorepo for a personal-use, event-sourced market microstructure research platform focused on:
+ - multi-source options/equities/news ingest (synthetic + live adapters),
+ - deterministic parent-event reconstruction over prints, quotes, and NBBO,
+ - explainable participant-style flow classification (not a single binary "smart money" flag),
+ - real-time + historical + replay delivery over REST and WebSocket,

+ ## How Print Classification Works (Current Approach)
+
+ Islandflow follows the same high-level philosophy captured in [smartmoney.md]:
+ the tape is informative but noisy, and a useful classifier should model multiple
+ participant-style hypotheses instead of forcing every print into one bucket.
+
+ 1. Ingest + normalize
+ 2. Reconstruct parent events
+ 3. Compute evidence features
+ 4. Score profile hypotheses
+ 5. Emit explainable artifacts

Expected Impact for End-Users

GitHub readers should understand Islandflow’s current value faster: what the app does, how data flows through the system, and why classification output is multi-profile and evidence-based rather than a simplistic label.

Validation

• Reviewed patch with git diff -- README.md.
• Ran git diff --check; no whitespace or patch format issues.
• Verified the heading image line remained present and unchanged at the top of the README.
• No runtime/tests were required because only documentation changed.

Issues, Limitations, and Mitigations

• README still summarizes classification behavior at a high level; detailed methodology remains in smartmoney.md and compute source.
• Because this is docs-only, there is no direct behavioral verification beyond content accuracy checks against current code paths.

Follow-up Work

• Add a compact architecture diagram in README linking services to public API channels.
• Add a short “classification caveats” subsection for expected false-positive classes.
• Consider adding a dedicated docs page that maps each profile ID to real payload fields and UI representation.