README Current-State Update

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.