Turn document · 2026-05-19 07:39 America/New_York

# README Current-State Update

Resolved the README merge conflict and rewrote the project overview so it matches the current Islandflow codebase, including the smart-money taxonomy, Next.js 16 update, news ingest, desktop shell, and current deployment posture.

README.md smart-money taxonomy Next.js 16.2.6 deployment docs

## Summary

The README no longer contains conflict markers. It now gives a concise but current description of the platform, its runtime services, public smart-money categories, environment knobs, and supported deployment workflow.

## Changes Made

- Resolved the conflicted README by preserving the useful project-state content and removing stale simplified sections.
- Added a first-class smart-money taxonomy section for the six public profiles: `institutional_directional`, `retail_whale`, `event_driven`, `vol_seller`, `arbitrage`, and `hedge_reactive`.
- Documented that smart-money events are now the semantic object, while legacy classifier hits and alerts remain compatibility surfaces.
- Updated the current implementation state to include Alpaca news ingest, profile-aware UI behavior, alert-context hydration, and the Electron shell.
- Recorded the Next.js update to `16.2.6` with React and React DOM `19.2.0`.
- Clarified deployment: Docker is still the supported VPS path, native Bun/systemd rollout is experimental, and scoped deploy flags are available.
- Aligned live-cache and web hot-window defaults with the current env examples and API defaults.

## Context

Recent commits showed the README branch was carrying a Next.js upgrade, Alpaca news support, smart-money event work, and deployment helper changes. The prior README mixed both sides of a merge conflict and did not explain the newer taxonomy-driven classifier model.

## Important Implementation Details

The README intentionally treats `FlowPacket` as an intermediate clustering bridge and `SmartMoneyEvent` as the current semantic surface. It also documents abstention and suppression behavior so readers do not mistake every large print for a forced smart-money label.

Deployment language now matches the current operations docs: `./deploy main` defaults to the Docker path, `--runtime native` is available but experimental, and native rollout still depends on systemd units and reverse-proxy preparation.

## Relevant Diff Snippets

Diff snippets are formatted for readability in the same spirit as diffs.com, with only the most relevant README changes shown here.

    +## Smart-Money Classification Taxonomy
    +
    +Islandflow now emits first-class `SmartMoneyEvent` records instead of treating old classifier hits as the final semantic object.
    +
    +| Profile ID | Meaning | Common evidence |
    +| --- | --- | --- |
    +| `institutional_directional` | Large directional parent flow with stronger institutional-style conviction. | premium, size, sweep/burst behavior, aggressor imbalance, quote quality |
    +| `retail_whale` | Large retail-style speculative bursts, often short-dated or attention-driven. | short-dated OTM concentration, burst prints, IV shock |
    +| `event_driven` | Flow aligned to known upcoming events. | event-calendar proximity, expiry after event, pre-event concentration |
    +| `vol_seller` | Premium-selling or short-volatility structure evidence. | sell-side premium, straddles/strangles |
    +| `arbitrage` | Multi-leg or symmetric structures with low directional exposure. | matched leg symmetry, near-flat directional bias |
    +| `hedge_reactive` | Hedge or dealer-reaction style flow around short-dated ATM/gamma context. | 0-2 DTE, near-ATM contracts, underlying move linkage |

    +## Deployment Workflow
    +
    +Docker remains the supported and recommended path for the current VPS.
    +
    +./deploy main
    +./deploy main --runtime docker
    +./deploy current-branch
    +./deploy current-branch --runtime docker
    +
    +Native deployment is opt-in and experimental:
    +
    +./deploy main --runtime native
    +./deploy current-branch --runtime native

## Expected Impact for End-Users

New contributors or future sessions should be able to read the README and understand what Islandflow currently does, which service owns each capability, how the smart-money labels should be interpreted, and which deployment command is appropriate for the VPS.

## Validation

- Confirmed no merge conflict markers remain with `rg -n "<<<<<<<|=======|>>>>>>>" README.md`.
- Ran `git diff --check`; no whitespace or patch-format issues were reported.
- Ran focused tests: `bun test packages/types/tests/options-flow.test.ts packages/types/tests/live.test.ts packages/storage/tests/smart-money-events.test.ts services/compute/tests/parent-events.test.ts`.
- Focused test result: 12 pass, 0 fail.

## Issues, Limitations, and Mitigations

- This was documentation-only, so no full production web build was run. The focused tests cover the smart-money/type/storage claims most relevant to the README update.
- The README summarizes environment variables instead of listing every low-level classifier and dark-inference threshold. Detailed knobs remain available in `.env.example` and service code.
- Native deployment remains experimental; the README calls that out directly and points to the dedicated native deployment document.

## Follow-up Work

- `islandflow-38p`: add native deployment unit templates and rollback helpers.
- `islandflow-932`: continue desktop follow-up native features.
- `islandflow-2db`: manually remove stale local-infra containers from the VPS when doing server hygiene.