Islandflow system reference
++ A compact anatomy map for the path a market print takes through ingest, the live + tape, flow packet construction, smart-money profiling, classifier hits, and alerts. +
+ ++ Ingest publishes the live market row. The API can show that row immediately as tape, + while compute consumes the signal stream and builds slower, richer derived events from + the same traceable print evidence. +
+
+ Options prints, option NBBO, equity prints, and equity quotes land on NATS subjects
+ such as options.prints, options.nbbo, and
+ equities.prints. Each event carries source_ts,
+ ingest_ts, seq, and trace_id.
+
+ The options ingest path enriches prints with contract metadata, NBBO side,
+ notional, ETF classification, and signal_pass. Signal-qualified rows
+ are published to options.prints.signal.
+
+ Compute consumes signal prints and NBBO context, groups nearby activity, derives
+ features, writes flow_packets, and publishes flow.packets.
+
+ A flow packet can produce a SmartMoneyEvent, one or more
+ ClassifierHitEvent rows, and an AlertEvent. The resulting
+ alert keeps evidence_refs back to packet and print identifiers.
+
+ A print is not yet a theory. It is a timed execution row plus enough enrichment to say + whether it deserves live attention and whether it can support later inference. +
+option_contract_idThe contract key, parsed into root, expiry, strike, and right when possible.price + sizeThe execution terms used for premium and notional.nbbo_sideWhere the trade printed versus bid, ask, midpoint, missing quote, or stale quote.signal_passWhether the print survives the configured smart-money, balanced, or all mode filter.underlying_idThe equity symbol or internal underlying identifier.price + sizeThe trade terms used for candles and equity context.offExchangeFlagA direct flag for off-exchange prints before dark inference adds interpretation.trace_idThe stable evidence handle used for joins, drawers, history, and replay.
+ Compute creates a FlowPacket when activity is strong enough to inspect as a
+ grouped unit. It stores member print ids, aggregate features, and join-quality metrics
+ so later events can explain what they used.
+
+ A SmartMoneyEvent is the parent interpretation of a flow packet. It keeps
+ packet ids and member print ids, then records profile probabilities, direction,
+ abstention state, and any suppression reasons.
+
+ Current profile ids include institutional_directional,
+ retail_whale, event_driven, vol_seller,
+ arbitrage, and hedge_reactive.
+
+ Direction is normalized as bullish, bearish,
+ neutral, mixed, or unknown, with profile reasons
+ kept beside the probability.
+
+ Special print context, stale quotes, missing NBBO coverage, or cross-like executions + can lower confidence or cause an abstained event rather than a confident call. +
++ Classifiers look at packet and smart-money context, then emit hit events with a + classifier id, confidence, direction, and explanation strings. They are deliberately + narrower than alerts. +
+| Layer | +Primary input | +Important fields | +What the operator sees | +
|---|---|---|---|
FlowPacket |
+ Signal option prints and quote context | +members, features, join_quality |
+ Grouped flow row, packet drawer, linked member prints | +
SmartMoneyEvent |
+ One flow packet plus event calendar context when available | +profile_scores, primary_direction, suppressed_reasons |
+ Smart-money profile row and profile reasoning | +
ClassifierHitEvent |
+ Derived parent event and packet feature thresholds | +classifier_id, confidence, direction, explanations |
+ Classifier feed row and decorators on linked tape rows | +
AlertEvent |
+ Flow packet plus one or more classifier hits | +score, severity, hits, evidence_refs |
+ Alert row, severity strip, alert context drawer | +
+ Alerts do not replace the underlying evidence. They score it, attach severity, and keep + enough references for the UI and API to reconstruct the supporting packet and prints. +
+AlertEvent {
+ source_ts
+ ingest_ts
+ seq
+ trace_id
+ score
+ severity
+ hits[]
+ evidence_refs[]
+ primary_profile_id?
+ profile_scores?
+}
+ Alert scoring combines packet premium, strongest classifier confidence, and hit count,
+ then maps the score into low, medium, or high
+ severity. The important operational detail is that the alert remains reversible:
+ open it, inspect the hit, inspect the packet, then inspect the print evidence.
+
+ Every major row carries cursor-friendly time metadata and a trace handle. The live API + uses NATS for fresh events, ClickHouse for snapshots and older history, and the same + schemas for replay. +
+
+ The terminal subscribes to channels including options, flow,
+ smart-money, classifier-hits, and alerts. Each
+ channel can deliver snapshots, events, watermarks, and history cursors.
+
+ Derived rows are persisted as flow_packets,
+ smart_money_events, classifier_hits, and
+ alerts. Alert context lookup resolves evidence references across those
+ tables and the option print store.
+
+ Three commits landed on Sunday, May 31, 2026. The day’s git-visible work centered on
+ documentation operations: repo guidance was trimmed in AGENTS.md, a new
+ standalone docs/anatomy.html reference page was added, and the GitHub Pages
+ mirror workflow was retargeted to publish into dirtydishes.github.io/islandflow.
+
+ Commit ab35533289b4 removed most duplicated repository-specific turn-doc
+ prose from AGENTS.md and replaced it with references back to the global
+ Codex instructions plus a smaller repo override block.
+
+ Commit 5074b7eeaa9e created docs/anatomy.html, updated the
+ generated docs index, and closed Beads task islandflow-5jt.
+
+ Commit 8933e29ae83d rewired .github/workflows/docs-pages.yml
+ to check out dirtydishes/dirtydishes.github.io, mirror
+ site/docs under islandflow, and push to that repository’s
+ master branch. The same commit closed islandflow-m3d and
+ left islandflow-8a6 open for token verification.
+
+ trim repo turn doc guidance reduced AGENTS.md by
+ removing duplicated turn-document instructions and keeping only the repo-specific
+ overrides: docs/turns location, impeccable usage,
+ @pierre/diffs/ssr for diff rendering, the minor/trivial exemption list,
+ and the completion checklist.
+
+ add anatomy reference page added a new standalone docs page and
+ updated the generated docs landing page so anatomy.html appears in the
+ root document listing. The Beads state added and closed
+ islandflow-5jt with the note that the page had been linked from the docs
+ index.
+
+ fix docs pages mirror target changed the GitHub Actions workflow
+ from pushing a local gh-pages branch to checking out
+ dirtydishes/dirtydishes.github.io, copying the generated docs into
+ pages/islandflow, and pushing back to the Pages repo’s
+ master branch. It also tightened the generated HTML formatting in
+ scripts/generate-docs-index.mjs, regenerated docs/index.html,
+ and added turn doc
+ docs/turns/2026-05-31-fix-docs-pages-mirror.html.
+
+ This report is anchored to local git history whose commit dates fall between
+ 2026-05-31 00:00:00 -0400 and 2026-06-01 00:00:00 -0400. No PR
+ merges appear in that window, so the summary is commit-first and file-first. Beads issue
+ references are only included where they were visible in the inspected commit diffs.
+
AGENTS.md kept the repo-specific overrides but stopped restating the global
+ turn-document policy in full, which should reduce drift between the repo file and
+ ~/.codex/AGENTS.md.
+ docs/turns or docs/general, and the generated docs index was
+ updated so it appears under the root category.
+ PAGES_REPOSITORY=dirtydishes/dirtydishes.github.io,
+ PAGES_BRANCH=master, and PAGES_PREFIX=islandflow.
+ DOCS_PAGES_TOKEN rather than the default
+ GITHUB_TOKEN, because it pushes to a different repository.
+ Docs Pages mirror target after 8933e29ae83d:
+
+PAGES_REPOSITORY=dirtydishes/dirtydishes.github.io
+PAGES_BRANCH=master
+PAGES_PREFIX=islandflowAGENTS.md and clearer repo-only overrides.
+ dirtydishes.github.io/islandflow/docs/ instead of relying on a
+ mismatched branch target.
+ git log scoped to May 31, 2026 to enumerate the three commits included
+ in this standup window.
+ git show --stat and targeted git show diffs to anchor the
+ changed files, workflow behavior, and visible Beads issue IDs for each commit.
+ docs/turns/2026-05-31-fix-docs-pages-mirror.html: local
+ node scripts/generate-docs-index.mjs, node --check on the
+ generator, YAML parsing for .github/workflows/docs-pages.yml, and
+ git diff --check.
+ AGENTS.md trim or the anatomy page beyond the committed file additions and
+ docs index linkage.
+ DOCS_PAGES_TOKEN is present and valid. That gap is already tracked in
+ islandflow-8a6.
+ islandflow-8a6: verify the GitHub Pages token for the docs mirror so the
+ updated workflow can push to dirtydishes/dirtydishes.github.io.
+ ab35533289b4 in the inspected history.
+ No files match that filter.
diff --git a/docs/turns/2026-05-31-fix-docs-pages-mirror.html b/docs/turns/2026-05-31-fix-docs-pages-mirror.html new file mode 100644 index 0000000..a15c6e2 --- /dev/null +++ b/docs/turns/2026-05-31-fix-docs-pages-mirror.html @@ -0,0 +1,198 @@ + + + + + +Repository turn report
+The docs publishing workflow now mirrors the generated static docs payload into the actual GitHub Pages site repository, dirtydishes/dirtydishes.github.io, under the islandflow/docs/ path.
Repaired the Pages publishing target so repository docs are copied to dirtydishes.github.io/islandflow/docs/ instead of attempting to force-push a gh-pages branch back to the mirrored islandflow repository.
dirtydishes/dirtydishes.github.io, branch master, and prefix islandflow.secrets.DOCS_PAGES_TOKEN.pages/islandflow/, which serves the docs at /islandflow/docs/..DS_Store files from the generated site payload before publishing.docs/index.html so the docs index reflects the current repository docs set.dirtydishes/dirtydishes.github.io while the automated mirror path awaits secret verification.The previous workflow built a valid static payload, but its publish step initialized a temporary Git repository and pushed gh-pages to github.com/$GITHUB_REPOSITORY. That targets the dirtydishes/islandflow mirror, not the user Pages repository that serves dirtydishes.github.io.
Cross-repository publishing cannot rely on the default GITHUB_TOKEN from the source workflow. The fixed workflow uses a dedicated secret token for the Pages site checkout and push.
https://dirtydishes.github.io/islandflow/docs/.master, matching the current remote state of dirtydishes/dirtydishes.github.io.islandflow/ subtree in the Pages repository, leaving any other site content alone.DOCS_PAGES_TOKEN with permission to read and write dirtydishes/dirtydishes.github.io.Rendered with @pierre/diffs/ssr using server-side generated markup so this report is readable offline without loading remote JavaScript.
+
Readers can browse the Islandflow docs at dirtydishes.github.io/islandflow/docs/ from the actual Pages site. Once DOCS_PAGES_TOKEN is configured, future updates should arrive through the automated mirror workflow instead of manual publication.
node scripts/generate-docs-index.mjs; it generated docs/index.html with 65 entries.node --check scripts/generate-docs-index.mjs..github/workflows/docs-pages.yml with Ruby YAML.git diff --check after tightening the generated index output.islandflow/docs to dirtydishes/dirtydishes.github.io and confirmed https://dirtydishes.github.io/islandflow/docs/ returns HTTP 200 with the docs index.bunx actionlint .github/workflows/docs-pages.yml still failed because the package did not expose a runnable executable in this environment.DOCS_PAGES_TOKEN exists in the GitHub mirror repository secrets and can push to dirtydishes/dirtydishes.github.io.islandflow-8a6: Add or verify DOCS_PAGES_TOKEN in the GitHub mirror repository secrets, then manually run the Publish Docs workflow after this branch lands on the mirrored main.