From 5074b7eeaa9ec9723187376f06ca104e09a43c22 Mon Sep 17 00:00:00 2001 From: dirtydishes Date: Sun, 31 May 2026 17:26:08 -0400 Subject: [PATCH 1/4] add anatomy reference page --- .beads/issues.jsonl | 1 + docs/anatomy.html | 893 ++++++++++++++++++++++++++++++++++++++++++++ docs/index.html | 103 ++--- 3 files changed, 950 insertions(+), 47 deletions(-) create mode 100644 docs/anatomy.html diff --git a/.beads/issues.jsonl b/.beads/issues.jsonl index c0fa90a..0e9785d 100644 --- a/.beads/issues.jsonl +++ b/.beads/issues.jsonl @@ -24,6 +24,7 @@ {"_type":"issue","id":"islandflow-ayo","title":"Drop stale backlog events from live fanout","description":"Follow-up to live freshness rollout: /ws/live was still fanning out stale backlog events for freshness-gated channels, which kept tape panes in Live feed behind despite active synthetic ingest. Gate fanout and cache ingest by freshness for options/nbbo/equities/flow.","status":"closed","priority":1,"issue_type":"bug","assignee":"dirtydishes","owner":"dishes@dpdrm.com","created_at":"2026-04-28T21:26:39Z","created_by":"dirtydishes","updated_at":"2026-04-28T21:26:44Z","started_at":"2026-04-28T21:26:44Z","closed_at":"2026-04-28T21:26:44Z","close_reason":"Completed","dependency_count":0,"dependent_count":0,"comment_count":0} {"_type":"issue","id":"islandflow-0v6","title":"Fix tape freshness, NBBO coverage, pause controls, and filter popup","description":"Implement the tape fixes requested for synthetic options notional sizing, strict live freshness, live-mode pause/resume behavior, stronger NBBO snapshot coverage, and moving flow filters behind a popup. Includes server-side live cache changes, web terminal state/UI changes, and tests for synthetic pricing, live snapshot freshness/NBBO retention, and live pause/filter interactions.","status":"closed","priority":1,"issue_type":"task","assignee":"dirtydishes","owner":"dishes@dpdrm.com","created_at":"2026-04-28T21:02:52Z","created_by":"dirtydishes","updated_at":"2026-04-28T21:13:38Z","started_at":"2026-04-28T21:02:57Z","closed_at":"2026-04-28T21:13:38Z","close_reason":"Completed","dependency_count":0,"dependent_count":0,"comment_count":0} {"_type":"issue","id":"islandflow-e4r","title":"Implement smart-money flow filtering and synthetic firehose modes","description":"Implement the approved multi-surface plan for named synthetic market profiles, options raw-vs-signal filtering, live/API filter contracts, Tape page client-side flow filters, firehose-readiness improvements, tests, and README updates.","status":"closed","priority":1,"issue_type":"feature","assignee":"dirtydishes","owner":"dishes@dpdrm.com","created_at":"2026-04-28T20:10:49Z","created_by":"dirtydishes","updated_at":"2026-04-28T20:29:29Z","started_at":"2026-04-28T20:10:53Z","closed_at":"2026-04-28T20:29:29Z","close_reason":"Implemented synthetic market profiles, options signal-path filtering, signal-aware API/replay contracts, Tape page filters, tests, and README updates. Follow-up tracked in islandflow-biq.","dependency_count":0,"dependent_count":0,"comment_count":0} +{"_type":"issue","id":"islandflow-5jt","title":"Add anatomy reference page","description":"Create a standalone docs/anatomy.html reference explaining how prints move through ingest, tape, flow packets, smart-money events, classifier hits, and alerts, including diagrams.","status":"closed","priority":2,"issue_type":"task","assignee":"dirtydishes","owner":"dishes@dpdrm.com","created_at":"2026-05-31T21:20:34Z","created_by":"dirtydishes","updated_at":"2026-05-31T21:25:54Z","started_at":"2026-05-31T21:20:44Z","closed_at":"2026-05-31T21:25:54Z","close_reason":"Added the standalone anatomy reference page and linked it from the docs index.","dependency_count":0,"dependent_count":0,"comment_count":0} {"_type":"issue","id":"islandflow-cig","title":"Expand CI quality gates","description":"Add a more robust CI workflow for the Bun/TypeScript monorepo, including formatting, linting, type checking, builds, and tests where appropriate.","status":"closed","priority":2,"issue_type":"task","assignee":"dirtydishes","owner":"dishes@dpdrm.com","created_at":"2026-05-30T06:29:33Z","created_by":"dirtydishes","updated_at":"2026-05-30T06:34:11Z","started_at":"2026-05-30T06:29:41Z","closed_at":"2026-05-30T06:34:11Z","close_reason":"Expanded CI quality gates with Biome formatting/linting, public API route checks, Docker snapshot validation, tests, typecheck, and web build validation.","dependency_count":0,"dependent_count":0,"comment_count":0} {"_type":"issue","id":"islandflow-3l6","title":"fix ci typecheck bun path resolution","description":"Forgejo CI fails in scripts/typecheck.ts because the script shells out to bunx, which expects bun on PATH. The runner installs Bun by absolute path, so the typecheck helper should use the current Bun executable instead of PATH lookup.","status":"closed","priority":2,"issue_type":"bug","assignee":"dirtydishes","owner":"dishes@dpdrm.com","created_at":"2026-05-30T05:34:55Z","created_by":"dirtydishes","updated_at":"2026-05-30T06:00:31Z","started_at":"2026-05-30T05:35:02Z","closed_at":"2026-05-30T06:00:31Z","close_reason":"Fixed the Forgejo CI terminal import mismatch by switching the terminal client component to a namespace import; verified locally and on Forgejo run #56.","dependency_count":0,"dependent_count":0,"comment_count":0} {"_type":"issue","id":"islandflow-wtg","title":"Harden drawer dialog focus behavior","description":"Fix terminal drawers so they expose modal dialog semantics, trap keyboard focus while open, and restore focus to the invoking control after close.","status":"closed","priority":2,"issue_type":"task","assignee":"dirtydishes","owner":"dishes@dpdrm.com","created_at":"2026-05-29T22:55:25Z","created_by":"dirtydishes","updated_at":"2026-05-29T23:09:45Z","started_at":"2026-05-29T22:56:22Z","closed_at":"2026-05-29T23:09:45Z","close_reason":"Implemented modal dialog semantics, focus trapping, Escape dismissal, focus restoration, validation, and turn documentation.","dependency_count":0,"dependent_count":0,"comment_count":0} diff --git a/docs/anatomy.html b/docs/anatomy.html new file mode 100644 index 0000000..0878ff9 --- /dev/null +++ b/docs/anatomy.html @@ -0,0 +1,893 @@ + + + + + + Islandflow Anatomy: Print to Alert + + + +
+
+
+
+

Islandflow system reference

+

From print to alert

+

+ 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. +

+ +
+ +
+ + Print to alert overview + + + + + + + Ingest + options.prints + equities.prints + + + Tape + signal rows + raw context + + + Compute + cluster + join features + + + FlowPacket + members[] + features{} + + + + + + + SmartMoney + profile_scores[] + primary_direction + + + ClassifierHit + classifier_id + confidence + + + Alert + score + severity + evidence_refs[] + + + + + + + ClickHouse history + API live fanout + replay cursors + + + + +
+ ingest + tape + derived + profile + alert +
+
+
+
+ +
+
+
+

The pipeline is two paths that meet again

+
+

+ 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. +

+
+ +
    +
  1. + 1 +
    + Adapters publish raw market events. +

    + 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. +

    +
    +
    2. +
  2. + 2 +
    + Signal prints become the options tape head. +

    + 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. +

    +
    +
    3. +
  3. + 3 +
    + Compute clusters print evidence into flow packets. +

    + Compute consumes signal prints and NBBO context, groups nearby activity, derives + features, writes flow_packets, and publishes flow.packets. +

    +
    +
    4. +
  4. + 4 +
    + Parent events, hits, and alerts preserve the evidence chain. +

    + 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. +

    +
    +
    5. +
+
+ +
+
+
+

Prints are the smallest inspectable fact

+
+

+ 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. +

+
+ +
+
+

OptionPrint

+
+
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.
+
+
+
+

EquityPrint

+
+
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.
+
+
+
+
+ +
+
+
+

Flow packets are parent evidence, not final conclusions

+
+

+ 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. +

+
+ +
+ + Flow packet anatomy + + + + + + + Print A + trace_id: opt-101 + + Print B + trace_id: opt-102 + + Print C + trace_id: opt-103 + + + FlowPacket + members: [opt-101, opt-102, opt-103] + features: total_premium, count, dte + nbbo_aggressive_buy_ratio + join_quality: coverage, age, spread + + + ClickHouse + flow_packets + + Live API + channel: flow + + + + + + + +
+
+ +
+
+
+

Smart-money events turn packet features into profiles

+
+

+ 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. +

+
+ +
+
+

Profiles

+

+ Current profile ids include institutional_directional, + retail_whale, event_driven, vol_seller, + arbitrage, and hedge_reactive. +

+
+
+

Direction

+

+ Direction is normalized as bullish, bearish, + neutral, mixed, or unknown, with profile reasons + kept beside the probability. +

+
+
+

Suppression

+

+ 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. +

+
+
+
+ +
+
+
+

Classifier hits are named detections with reasons

+
+

+ 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. +

+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
LayerPrimary inputImportant fieldsWhat the operator sees
FlowPacketSignal option prints and quote contextmembers, features, join_qualityGrouped flow row, packet drawer, linked member prints
SmartMoneyEventOne flow packet plus event calendar context when availableprofile_scores, primary_direction, suppressed_reasonsSmart-money profile row and profile reasoning
ClassifierHitEventDerived parent event and packet feature thresholdsclassifier_id, confidence, direction, explanationsClassifier feed row and decorators on linked tape rows
AlertEventFlow packet plus one or more classifier hitsscore, severity, hits, evidence_refsAlert row, severity strip, alert context drawer
+
+
+ +
+
+
+

Alerts package evidence for action

+
+

+ 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. +

+
+
+
+ +
+
+
+

Traceability is the contract between live and replay

+
+

+ 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. +

+
+ +
+
+

Live channels

+

+ The terminal subscribes to channels including options, flow, + smart-money, classifier-hits, and alerts. Each + channel can deliver snapshots, events, watermarks, and history cursors. +

+
+
+

History tables

+

+ 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. +

+
+
+
+ +
+

+ Reference based on the current Islandflow TypeScript schemas, NATS subjects, compute + service, storage tables, and live API channel names. +

+
+
+ + diff --git a/docs/index.html b/docs/index.html index 211c5ac..967e43d 100644 --- a/docs/index.html +++ b/docs/index.html @@ -207,20 +207,20 @@
-
35 of 35 files shown
+
36 of 36 files shown
+root 3

turns 28

- +

daily-git 1

- +

general 2

- +

plans 2

- +
-

root 2

+

root 3

From 8933e29ae83d8531c29de5e7fa92b5e915819142 Mon Sep 17 00:00:00 2001 From: dirtydishes Date: Sun, 31 May 2026 18:13:20 -0400 Subject: [PATCH 2/4] fix docs pages mirror target --- .beads/issues.jsonl | 2 + .github/workflows/docs-pages.yml | 45 +- docs/index.html | 401 ++++++++++++------ .../2026-05-31-fix-docs-pages-mirror.html | 198 +++++++++ scripts/generate-docs-index.mjs | 12 +- 5 files changed, 508 insertions(+), 150 deletions(-) create mode 100644 docs/turns/2026-05-31-fix-docs-pages-mirror.html diff --git a/.beads/issues.jsonl b/.beads/issues.jsonl index 0e9785d..19d9115 100644 --- a/.beads/issues.jsonl +++ b/.beads/issues.jsonl @@ -1,3 +1,4 @@ +{"_type":"issue","id":"islandflow-m3d","title":"fix docs mirroring to github pages","description":"The repository docs folder is supposed to mirror to dirtydishes.github.io for GitHub Pages, but the mirroring is not working. Investigate the docs publishing workflow and repair the configuration or scripts so docs can be published reliably.","status":"closed","priority":1,"issue_type":"bug","assignee":"dirtydishes","owner":"dishes@dpdrm.com","created_at":"2026-05-31T22:05:48Z","created_by":"dirtydishes","updated_at":"2026-05-31T22:12:26Z","started_at":"2026-05-31T22:05:56Z","closed_at":"2026-05-31T22:12:26Z","close_reason":"Updated docs Pages workflow to publish into dirtydishes/dirtydishes.github.io under islandflow/docs, tightened docs index generation, regenerated docs index, and documented validation/limitations.","dependency_count":0,"dependent_count":0,"comment_count":0} {"_type":"issue","id":"islandflow-2op","title":"[bug] Desktop app unclickable and no live data in hosted shell","description":"## Summary\\nDesktop Electron shell appears fully non-interactive (clicks do not work) and no live market data reaches the UI.\\n\\n## Why this matters\\nDesktop wrapper is currently unusable for core workflow and blocks users from validating market streams outside browser.\\n\\n## Scope\\nReproduce issue locally, identify root cause(s) in Electron shell and frontend integration, implement fix, and validate interactivity + data flow end-to-end.\\n\\n## Acceptance Criteria\\n- Desktop app responds to pointer interactions (navigation/actions clickable)\\n- Live data stream connects and updates UI in desktop mode\\n- Regression coverage or guardrails added where practical\\n- Findings and validation documented","status":"in_progress","priority":1,"issue_type":"bug","assignee":"dirtydishes","owner":"dishes@dpdrm.com","created_at":"2026-05-24T04:23:55Z","created_by":"dirtydishes","updated_at":"2026-05-24T04:23:57Z","started_at":"2026-05-24T04:23:57Z","dependency_count":0,"dependent_count":0,"comment_count":0} {"_type":"issue","id":"islandflow-jad","title":"Sync docs pages workflow fix to github mirror","description":"GitHub is still running an older docs Pages workflow with configure-pages because github/main is behind forgejo/main. Push the already-fixed workflow commit to the GitHub mirror so Actions runs the gh-pages branch deployment flow instead.","status":"closed","priority":1,"issue_type":"task","assignee":"dirtydishes","owner":"dishes@dpdrm.com","created_at":"2026-05-23T22:27:46Z","created_by":"dirtydishes","updated_at":"2026-05-23T22:28:24Z","started_at":"2026-05-23T22:28:10Z","closed_at":"2026-05-23T22:28:24Z","close_reason":"Closed","dependency_count":0,"dependent_count":0,"comment_count":0} {"_type":"issue","id":"islandflow-bc7","title":"Fix docs Pages workflow configure-pages failure","description":"Replace the current docs Pages deployment flow so workflow runs succeed even when configure-pages cannot read or enable the site. Keep published docs target behavior for dirtydishes.github.io/islandflow/docs.","status":"closed","priority":1,"issue_type":"bug","assignee":"dirtydishes","owner":"dishes@dpdrm.com","created_at":"2026-05-23T22:23:28Z","created_by":"dirtydishes","updated_at":"2026-05-23T22:25:19Z","started_at":"2026-05-23T22:23:31Z","closed_at":"2026-05-23T22:25:19Z","close_reason":"Closed","dependency_count":0,"dependent_count":0,"comment_count":0} @@ -24,6 +25,7 @@ {"_type":"issue","id":"islandflow-ayo","title":"Drop stale backlog events from live fanout","description":"Follow-up to live freshness rollout: /ws/live was still fanning out stale backlog events for freshness-gated channels, which kept tape panes in Live feed behind despite active synthetic ingest. Gate fanout and cache ingest by freshness for options/nbbo/equities/flow.","status":"closed","priority":1,"issue_type":"bug","assignee":"dirtydishes","owner":"dishes@dpdrm.com","created_at":"2026-04-28T21:26:39Z","created_by":"dirtydishes","updated_at":"2026-04-28T21:26:44Z","started_at":"2026-04-28T21:26:44Z","closed_at":"2026-04-28T21:26:44Z","close_reason":"Completed","dependency_count":0,"dependent_count":0,"comment_count":0} {"_type":"issue","id":"islandflow-0v6","title":"Fix tape freshness, NBBO coverage, pause controls, and filter popup","description":"Implement the tape fixes requested for synthetic options notional sizing, strict live freshness, live-mode pause/resume behavior, stronger NBBO snapshot coverage, and moving flow filters behind a popup. Includes server-side live cache changes, web terminal state/UI changes, and tests for synthetic pricing, live snapshot freshness/NBBO retention, and live pause/filter interactions.","status":"closed","priority":1,"issue_type":"task","assignee":"dirtydishes","owner":"dishes@dpdrm.com","created_at":"2026-04-28T21:02:52Z","created_by":"dirtydishes","updated_at":"2026-04-28T21:13:38Z","started_at":"2026-04-28T21:02:57Z","closed_at":"2026-04-28T21:13:38Z","close_reason":"Completed","dependency_count":0,"dependent_count":0,"comment_count":0} {"_type":"issue","id":"islandflow-e4r","title":"Implement smart-money flow filtering and synthetic firehose modes","description":"Implement the approved multi-surface plan for named synthetic market profiles, options raw-vs-signal filtering, live/API filter contracts, Tape page client-side flow filters, firehose-readiness improvements, tests, and README updates.","status":"closed","priority":1,"issue_type":"feature","assignee":"dirtydishes","owner":"dishes@dpdrm.com","created_at":"2026-04-28T20:10:49Z","created_by":"dirtydishes","updated_at":"2026-04-28T20:29:29Z","started_at":"2026-04-28T20:10:53Z","closed_at":"2026-04-28T20:29:29Z","close_reason":"Implemented synthetic market profiles, options signal-path filtering, signal-aware API/replay contracts, Tape page filters, tests, and README updates. Follow-up tracked in islandflow-biq.","dependency_count":0,"dependent_count":0,"comment_count":0} +{"_type":"issue","id":"islandflow-8a6","title":"verify github pages token for docs mirror","description":"The docs mirror workflow now publishes islandflow/docs into dirtydishes/dirtydishes.github.io, but the GitHub Actions secret DOCS_PAGES_TOKEN must exist and have permission to push to that Pages repository. Verify the secret is configured and manually run the Publish Docs workflow after the mirror branch lands.","status":"open","priority":2,"issue_type":"task","owner":"dishes@dpdrm.com","created_at":"2026-05-31T22:12:27Z","created_by":"dirtydishes","updated_at":"2026-05-31T22:12:27Z","dependency_count":0,"dependent_count":0,"comment_count":0} {"_type":"issue","id":"islandflow-5jt","title":"Add anatomy reference page","description":"Create a standalone docs/anatomy.html reference explaining how prints move through ingest, tape, flow packets, smart-money events, classifier hits, and alerts, including diagrams.","status":"closed","priority":2,"issue_type":"task","assignee":"dirtydishes","owner":"dishes@dpdrm.com","created_at":"2026-05-31T21:20:34Z","created_by":"dirtydishes","updated_at":"2026-05-31T21:25:54Z","started_at":"2026-05-31T21:20:44Z","closed_at":"2026-05-31T21:25:54Z","close_reason":"Added the standalone anatomy reference page and linked it from the docs index.","dependency_count":0,"dependent_count":0,"comment_count":0} {"_type":"issue","id":"islandflow-cig","title":"Expand CI quality gates","description":"Add a more robust CI workflow for the Bun/TypeScript monorepo, including formatting, linting, type checking, builds, and tests where appropriate.","status":"closed","priority":2,"issue_type":"task","assignee":"dirtydishes","owner":"dishes@dpdrm.com","created_at":"2026-05-30T06:29:33Z","created_by":"dirtydishes","updated_at":"2026-05-30T06:34:11Z","started_at":"2026-05-30T06:29:41Z","closed_at":"2026-05-30T06:34:11Z","close_reason":"Expanded CI quality gates with Biome formatting/linting, public API route checks, Docker snapshot validation, tests, typecheck, and web build validation.","dependency_count":0,"dependent_count":0,"comment_count":0} {"_type":"issue","id":"islandflow-3l6","title":"fix ci typecheck bun path resolution","description":"Forgejo CI fails in scripts/typecheck.ts because the script shells out to bunx, which expects bun on PATH. The runner installs Bun by absolute path, so the typecheck helper should use the current Bun executable instead of PATH lookup.","status":"closed","priority":2,"issue_type":"bug","assignee":"dirtydishes","owner":"dishes@dpdrm.com","created_at":"2026-05-30T05:34:55Z","created_by":"dirtydishes","updated_at":"2026-05-30T06:00:31Z","started_at":"2026-05-30T05:35:02Z","closed_at":"2026-05-30T06:00:31Z","close_reason":"Fixed the Forgejo CI terminal import mismatch by switching the terminal client component to a namespace import; verified locally and on Forgejo run #56.","dependency_count":0,"dependent_count":0,"comment_count":0} diff --git a/.github/workflows/docs-pages.yml b/.github/workflows/docs-pages.yml index bb72ee0..5fc6bcb 100644 --- a/.github/workflows/docs-pages.yml +++ b/.github/workflows/docs-pages.yml @@ -11,7 +11,7 @@ on: workflow_dispatch: permissions: - contents: write + contents: read concurrency: group: "docs-pages" @@ -20,6 +20,10 @@ concurrency: jobs: publish: runs-on: ubuntu-latest + env: + PAGES_REPOSITORY: dirtydishes/dirtydishes.github.io + PAGES_BRANCH: master + PAGES_PREFIX: islandflow steps: - name: Checkout uses: actions/checkout@v5 @@ -29,26 +33,41 @@ jobs: - name: Prepare static site payload run: | + rm -rf site mkdir -p site/docs cp -R docs/. site/docs/ printf '%s\n' 'Islandflow DocsContinue to docs' > site/index.html touch site/.nojekyll - - name: Publish to gh-pages branch - env: - GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + - name: Checkout GitHub Pages site + uses: actions/checkout@v5 + with: + repository: ${{ env.PAGES_REPOSITORY }} + ref: ${{ env.PAGES_BRANCH }} + token: ${{ secrets.DOCS_PAGES_TOKEN }} + path: pages + fetch-depth: 0 + + - name: Mirror docs into Pages site run: | set -euo pipefail - rm -rf .gh-pages-tmp - mkdir .gh-pages-tmp - cp -R site/. .gh-pages-tmp/ - cd .gh-pages-tmp + rm -rf "pages/${PAGES_PREFIX}" + mkdir -p "pages/${PAGES_PREFIX}" + cp -R site/. "pages/${PAGES_PREFIX}/" + touch pages/.nojekyll - git init - git checkout -b gh-pages + - name: Commit and push Pages mirror + run: | + set -euo pipefail + cd pages git config user.name "github-actions[bot]" git config user.email "41898282+github-actions[bot]@users.noreply.github.com" - git add -A - git commit -m "publish docs from ${GITHUB_SHA}" + git add "${PAGES_PREFIX}" .nojekyll - git push --force "https://x-access-token:${GITHUB_TOKEN}@github.com/${GITHUB_REPOSITORY}.git" gh-pages:gh-pages + if git diff --cached --quiet; then + echo "No docs changes to publish." + exit 0 + fi + + git commit -m "publish islandflow docs from ${GITHUB_SHA}" + git push origin "HEAD:${PAGES_BRANCH}" diff --git a/docs/index.html b/docs/index.html index 967e43d..8e297ae 100644 --- a/docs/index.html +++ b/docs/index.html @@ -207,100 +207,274 @@
-
36 of 36 files shown
+
64 of 64 files shown
-
-
-
-

turns 28

+
+

turns 52

- -

daily-git 1

- -
-

general 2

+

general 6

- -

plans 2

- -

root 3

-
-
+

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..b065c76 --- /dev/null +++ b/docs/turns/2026-05-31-fix-docs-pages-mirror.html @@ -0,0 +1,198 @@ + + + + + + Turn Report - Fix Docs Pages Mirror + + + +
+
+

Repository turn report

+

Fix docs mirroring to dirtydishes.github.io

+

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.

+
May 31, 2026Beads: islandflow-m3dWorkflow: .github/workflows/docs-pages.yml
+
+

Summary

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.

+

Changes Made

  • Changed the workflow permission from write to read for the source repository, because publishing now happens through the target Pages checkout.
  • Added explicit Pages target settings for dirtydishes/dirtydishes.github.io, branch master, and prefix islandflow.
  • Added a target-repository checkout that uses secrets.DOCS_PAGES_TOKEN.
  • Mirrors the static payload into pages/islandflow/, which serves the docs at /islandflow/docs/.
  • Commits and pushes only when the generated mirror content actually changed.
  • Tightened the docs index generator so regenerated HTML does not introduce trailing whitespace.
  • Regenerated docs/index.html so the docs index reflects the current repository docs set.
+

Context

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.

+

Important Implementation Details

  • The public URL remains https://dirtydishes.github.io/islandflow/docs/.
  • The target repository branch is master, matching the current remote state of dirtydishes/dirtydishes.github.io.
  • The workflow removes and replaces only the islandflow/ subtree in the Pages repository, leaving any other site content alone.
  • The workflow requires a GitHub Actions secret named DOCS_PAGES_TOKEN with permission to read and write dirtydishes/dirtydishes.github.io.
+

Relevant Diff Snippets

Rendered with @pierre/diffs/ssr using server-side generated markup so this report is readable offline without loading remote JavaScript.

.github/workflows/docs-pages.yml
-13+32
10 unmodified lines
11
12
13
14
15
16
17
2 unmodified lines
20
21
22
23
24
25
3 unmodified lines
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
10 unmodified lines
  workflow_dispatch:

+
permissions:
  contents: write

+
concurrency:
  group: "docs-pages"
2 unmodified lines
jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v5
3 unmodified lines

+
      - name: Prepare static site payload
        run: |
          mkdir -p site/docs
          cp -R docs/. site/docs/
          printf '%s\n' '<!doctype html><meta charset="utf-8"><meta http-equiv="refresh" content="0; url=https://dirtydishes.github.io/islandflow/docs/"><title>Islandflow Docs</title><a href="https://dirtydishes.github.io/islandflow/docs/">Continue to docs</a>' > site/index.html
          touch site/.nojekyll

+
      - name: Publish to gh-pages branch
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          set -euo pipefail
          rm -rf .gh-pages-tmp
          mkdir .gh-pages-tmp
          cp -R site/. .gh-pages-tmp/
          cd .gh-pages-tmp

+
          git init
          git checkout -b gh-pages
          git config user.name "github-actions[bot]"
          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
          git add -A
          git commit -m "publish docs from ${GITHUB_SHA}"

+
          git push --force "https://x-access-token:${GITHUB_TOKEN}@github.com/${GITHUB_REPOSITORY}.git" gh-pages:gh-pages
10 unmodified lines
11
12
13
14
15
16
17
2 unmodified lines
20
21
22
23
24
25
26
27
28
29
3 unmodified lines
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
10 unmodified lines
  workflow_dispatch:

+
permissions:
  contents: read

+
concurrency:
  group: "docs-pages"
2 unmodified lines
jobs:
  publish:
    runs-on: ubuntu-latest
    env:
      PAGES_REPOSITORY: dirtydishes/dirtydishes.github.io
      PAGES_BRANCH: master
      PAGES_PREFIX: islandflow
    steps:
      - name: Checkout
        uses: actions/checkout@v5
3 unmodified lines

+
      - name: Prepare static site payload
        run: |
          rm -rf site
          mkdir -p site/docs
          cp -R docs/. site/docs/
          printf '%s\n' '<!doctype html><meta charset="utf-8"><meta http-equiv="refresh" content="0; url=https://dirtydishes.github.io/islandflow/docs/"><title>Islandflow Docs</title><a href="https://dirtydishes.github.io/islandflow/docs/">Continue to docs</a>' > site/index.html
          touch site/.nojekyll

+
      - name: Checkout GitHub Pages site
        uses: actions/checkout@v5
        with:
          repository: ${{ env.PAGES_REPOSITORY }}
          ref: ${{ env.PAGES_BRANCH }}
          token: ${{ secrets.DOCS_PAGES_TOKEN }}
          path: pages
          fetch-depth: 0

+
      - name: Mirror docs into Pages site
        run: |
          set -euo pipefail
          rm -rf "pages/${PAGES_PREFIX}"
          mkdir -p "pages/${PAGES_PREFIX}"
          cp -R site/. "pages/${PAGES_PREFIX}/"
          touch pages/.nojekyll

+
      - name: Commit and push Pages mirror
        run: |
          set -euo pipefail
          cd pages
          git config user.name "github-actions[bot]"
          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
          git add "${PAGES_PREFIX}" .nojekyll

+
          if git diff --cached --quiet; then
            echo "No docs changes to publish."
            exit 0
          fi

+
          git commit -m "publish islandflow docs from ${GITHUB_SHA}"
          git push origin "HEAD:${PAGES_BRANCH}"
+
scripts/generate-docs-index.mjs
-8+4
128 unmodified lines
129
130
131
132
133
134
135
136
2 unmodified lines
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
128 unmodified lines
        .map((entry) => {
          const extension = path.extname(entry.relativePath).replace(".", "") || "file";
          const searchable = `${entry.relativePath} ${category}`.toLowerCase();
          return `
            <li class="doc-item" data-search="${escapeHtml(searchable)}">
              <a class="doc-link" href="${docsHref(entry.relativePath)}">${escapeHtml(
                entry.relativePath
              )}</a>
2 unmodified lines
                <span>${escapeHtml(formatBytes(entry.sizeBytes))}</span>
                <span>${escapeHtml(dateFormatter.format(entry.modifiedAt))}</span>
              </div>
            </li>
          `;
        })
        .join("\n");

+
      return `
        <section class="group" id="category-${escapeHtml(category)}">
          <h2>${escapeHtml(category)} <span>${entries.length}</span></h2>
          <ul class="doc-list">
            ${entryMarkup}
          </ul>
        </section>
      `;
    })
    .join("\n");

+
128 unmodified lines
129
130
131
132
133
134
135
2 unmodified lines
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
128 unmodified lines
        .map((entry) => {
          const extension = path.extname(entry.relativePath).replace(".", "") || "file";
          const searchable = `${entry.relativePath} ${category}`.toLowerCase();
          return `            <li class="doc-item" data-search="${escapeHtml(searchable)}">
              <a class="doc-link" href="${docsHref(entry.relativePath)}">${escapeHtml(
                entry.relativePath
              )}</a>
2 unmodified lines
                <span>${escapeHtml(formatBytes(entry.sizeBytes))}</span>
                <span>${escapeHtml(dateFormatter.format(entry.modifiedAt))}</span>
              </div>
            </li>`;
        })
        .join("\n");

+
      return `        <section class="group" id="category-${escapeHtml(category)}">
          <h2>${escapeHtml(category)} <span>${entries.length}</span></h2>
          <ul class="doc-list">
            ${entryMarkup}
          </ul>
        </section>`;
    })
    .join("\n");

+
+

Expected Impact for End-Users

Once the workflow runs on GitHub with DOCS_PAGES_TOKEN configured, readers should be able to browse the Islandflow docs at dirtydishes.github.io/islandflow/docs/ from the actual Pages site instead of depending on a missing or unconfigured project gh-pages branch.

+

Validation

  • Passed: Ran node scripts/generate-docs-index.mjs; it generated docs/index.html with 64 entries.
  • Passed: Ran node --check scripts/generate-docs-index.mjs.
  • Passed: Parsed .github/workflows/docs-pages.yml with Ruby YAML.
  • Passed: Ran git diff --check after tightening the generated index output.
  • Not completed: bunx actionlint .github/workflows/docs-pages.yml still failed because the package did not expose a runnable executable in this environment.
+

Issues, Limitations, and Mitigations

  • The workflow will fail until DOCS_PAGES_TOKEN exists in the GitHub mirror repository secrets and can push to dirtydishes/dirtydishes.github.io.
  • This was validated locally for generation and YAML syntax, but the cross-repository push itself can only be fully verified by a GitHub Actions run.
  • The docs index includes file modified timestamps, so regenerating it can change ordering and metadata when local mtimes differ from the committed version.
+

Follow-up Work

  • 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.
  • Consider replacing timestamp-based docs index ordering with commit dates or filenames so generated output is less sensitive to local filesystem mtimes.
+
+ + diff --git a/scripts/generate-docs-index.mjs b/scripts/generate-docs-index.mjs index 4123a4e..b3a426a 100644 --- a/scripts/generate-docs-index.mjs +++ b/scripts/generate-docs-index.mjs @@ -129,8 +129,7 @@ function renderDocument(items) { .map((entry) => { const extension = path.extname(entry.relativePath).replace(".", "") || "file"; const searchable = `${entry.relativePath} ${category}`.toLowerCase(); - return ` -
  • + return `
  • ${escapeHtml( entry.relativePath )} @@ -139,19 +138,16 @@ function renderDocument(items) { ${escapeHtml(formatBytes(entry.sizeBytes))} ${escapeHtml(dateFormatter.format(entry.modifiedAt))} -
    • - `; + `; }) .join("\n"); - return ` -
    + return `

    ${escapeHtml(category)} ${entries.length}

      ${entryMarkup}
    -
    - `; +
    `; }) .join("\n"); From 36d1b12e725fa9c502306efa8e9d82548dcb53e1 Mon Sep 17 00:00:00 2001 From: dirtydishes Date: Mon, 1 Jun 2026 09:04:50 -0400 Subject: [PATCH 3/4] docs(general): add May 31 standup summary --- .beads/issues.jsonl | 1 + ...2026-06-01-standup-summary-2026-05-31.html | 519 ++++++++++++++++++ docs/index.html | 16 +- 3 files changed, 532 insertions(+), 4 deletions(-) create mode 100644 docs/general/2026-06-01-standup-summary-2026-05-31.html diff --git a/.beads/issues.jsonl b/.beads/issues.jsonl index 19d9115..b896909 100644 --- a/.beads/issues.jsonl +++ b/.beads/issues.jsonl @@ -99,6 +99,7 @@ {"_type":"issue","id":"islandflow-zs0","title":"Migrate terminal UI to smart-money profiles","description":"Migrate apps/web terminal rendering to consume SmartMoneyEvent directly: primary profile, probability ladder, reason codes, and suppression/abstention state, while preserving legacy alert/classifier displays during the bridge.","status":"closed","priority":2,"issue_type":"task","owner":"dishes@dpdrm.com","created_at":"2026-05-04T21:35:23Z","created_by":"dirtydishes","updated_at":"2026-05-05T05:39:58Z","closed_at":"2026-05-05T05:39:58Z","close_reason":"Completed terminal smart-money profile migration","dependency_count":0,"dependent_count":0,"comment_count":0} {"_type":"issue","id":"islandflow-igk","title":"Add plan mode","description":"Implement a user-facing plan mode in the application so users can switch into planning before taking action. Scope to be clarified from existing app patterns.","status":"closed","priority":2,"issue_type":"feature","owner":"dishes@dpdrm.com","created_at":"2026-05-04T04:22:37Z","created_by":"dirtydishes","updated_at":"2026-05-04T04:26:18Z","started_at":"2026-05-04T04:22:40Z","closed_at":"2026-05-04T04:26:18Z","close_reason":"Implemented as a global pi extension toggled with Shift+P","dependency_count":0,"dependent_count":0,"comment_count":0} {"_type":"issue","id":"islandflow-biq","title":"Finish raw live options delivery and filter/backpressure observability","description":"The smart-money signal path and Tape filters are in place, but the next firehose pass should finish server-side selective raw live delivery for options subscriptions and add explicit filtered-out/backpressure observability for API/web counters. This was discovered while landing islandflow-e4r.\n","status":"in_progress","priority":2,"issue_type":"task","assignee":"dirtydishes","owner":"dishes@dpdrm.com","created_at":"2026-04-28T20:28:58Z","created_by":"dirtydishes","updated_at":"2026-04-29T03:54:12Z","started_at":"2026-04-29T03:54:12Z","dependencies":[{"issue_id":"islandflow-biq","depends_on_id":"islandflow-e4r","type":"discovered-from","created_at":"2026-04-28T16:28:58Z","created_by":"auto-import","metadata":"{}"}],"dependency_count":0,"dependent_count":0,"comment_count":0} +{"_type":"issue","id":"islandflow-3f4","title":"Publish May 31 standup git summary","description":"## Summary\nCreate the daily standup HTML summary for 2026-05-31 git activity in docs/general and regenerate any supporting docs index entries.\n\n## Why this matters\nThe team needs a grounded, commit-anchored standup artifact for May 31 repository activity.\n\n## Scope\nInspect May 31 git history, write the summary document in docs/general, update related generated docs metadata if needed, and close out the task.","status":"closed","priority":3,"issue_type":"task","assignee":"dirtydishes","owner":"dishes@dpdrm.com","created_at":"2026-06-01T13:02:21Z","created_by":"dirtydishes","updated_at":"2026-06-01T13:04:45Z","started_at":"2026-06-01T13:02:29Z","closed_at":"2026-06-01T13:04:45Z","close_reason":"Added docs/general standup summary for 2026-05-31 and verified docs index discovery.","dependency_count":0,"dependent_count":0,"comment_count":0} {"_type":"issue","id":"islandflow-6ak","title":"Clarify turn doc diff rendering instructions","description":"Make AGENTS.md explicit that turn documents should render diffs with the @pierre/diffs/ssr library import instead of attempting to run @pierre/diffs through bunx.","status":"closed","priority":3,"issue_type":"task","assignee":"dirtydishes","owner":"dishes@dpdrm.com","created_at":"2026-05-30T02:01:59Z","created_by":"dirtydishes","updated_at":"2026-05-30T02:02:27Z","started_at":"2026-05-30T02:02:00Z","closed_at":"2026-05-30T02:02:27Z","close_reason":"Updated AGENTS.md to require @pierre/diffs/ssr rendering, forbid bunx @pierre/diffs attempts, and include a known-good preloadPatchDiff recipe.","dependency_count":0,"dependent_count":0,"comment_count":0} {"_type":"issue","id":"islandflow-3kn","title":"Summarize 2026-05-28 git activity","description":"Prepare the standup-ready summary of yesterday's git activity, grounded in commits, PRs, and touched files, and store the HTML report in docs/general.","status":"closed","priority":3,"issue_type":"task","assignee":"dirtydishes","owner":"dishes@dpdrm.com","created_at":"2026-05-29T13:02:25Z","created_by":"dirtydishes","updated_at":"2026-05-29T13:04:23Z","started_at":"2026-05-29T13:02:33Z","closed_at":"2026-05-29T13:04:23Z","close_reason":"Closed","dependency_count":0,"dependent_count":0,"comment_count":0} {"_type":"issue","id":"islandflow-3ys","title":"Expand Forgejo CI beyond the fast validate path","description":"Add follow-on Forgejo CI jobs after the initial baseline is stable. This should cover deferred work such as Docker image builds for deployment/docker, service-container integration tests for NATS/Redis/ClickHouse paths, and any later deploy or release automation that should not block the first fast PR gate.","status":"open","priority":3,"issue_type":"task","owner":"dishes@dpdrm.com","created_at":"2026-05-24T00:34:09Z","created_by":"dirtydishes","updated_at":"2026-05-24T00:34:09Z","dependency_count":0,"dependent_count":0,"comment_count":0} diff --git a/docs/general/2026-06-01-standup-summary-2026-05-31.html b/docs/general/2026-06-01-standup-summary-2026-05-31.html new file mode 100644 index 0000000..dda5cc6 --- /dev/null +++ b/docs/general/2026-06-01-standup-summary-2026-05-31.html @@ -0,0 +1,519 @@ + + + + + + Standup Summary for 2026-05-31 + + + + + + +
    +
    + Daily Git Summary +

    Standup Summary for 2026-05-31

    +

    + 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. +

    +
    +
    + Commits inspected + 3 on 2026-05-31 +
    +
    + Files touched + 6 unique files +
    +
    + Tracked issues + islandflow-5jt, islandflow-m3d +
    +
    + Open follow-up + islandflow-8a6 +
    +
    +
    + +
    +

    Summary

    +
    +
    +

    Repo turn-document rules were tightened and shortened.

    +

    + 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. +

    +
    +
    +

    An anatomy explainer page was added to the docs set.

    +

    + Commit 5074b7eeaa9e created docs/anatomy.html, updated the + generated docs index, and closed Beads task islandflow-5jt. +

    +
    +
    +

    The docs mirror workflow was pointed at the actual Pages target.

    +

    + 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. +

    +
    +
    +
    + +
    +

    Changes Made

    +
    +
    +
    + ab35533289b4 + 2026-05-31 09:29 EDT + docs policy trim +
    +

    + 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. +

    +
    + AGENTS.md +
    +
    + +
    +
    + 5074b7eeaa9e + 2026-05-31 17:26 EDT + new docs surface +
    +

    + 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. +

    +
    + docs/anatomy.html + docs/index.html + .beads/issues.jsonl +
    +
    + +
    +
    + 8933e29ae83d + 2026-05-31 18:13 EDT + docs deploy fix +
    +

    + 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. +

    +
    + .github/workflows/docs-pages.yml + scripts/generate-docs-index.mjs + docs/index.html + docs/turns/2026-05-31-fix-docs-pages-mirror.html + .beads/issues.jsonl +
    +
    +
    +
    + +
    +

    Context

    +

    + 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. +

    +
    + +
    +

    Important Implementation Details

    +
      +
    • + 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. +
      • +
    • + The anatomy page landed as a standalone HTML asset at the docs root rather than under + docs/turns or docs/general, and the generated docs index was + updated so it appears under the root category. +
      • +
    • + The docs mirror workflow now uses these environment values inside the workflow job: + PAGES_REPOSITORY=dirtydishes/dirtydishes.github.io, + PAGES_BRANCH=master, and PAGES_PREFIX=islandflow. +
      • +
    • + The mirror job now depends on DOCS_PAGES_TOKEN rather than the default + GITHUB_TOKEN, because it pushes to a different repository. +
      • +
    • + The docs index generator change was mostly structural formatting: the rendered HTML for + list items and sections became tighter without changing the index’s overall categories or + sorting behavior. +
      • +
    + 
    Docs Pages mirror target after 8933e29ae83d:
+
+PAGES_REPOSITORY=dirtydishes/dirtydishes.github.io
+PAGES_BRANCH=master
+PAGES_PREFIX=islandflow
    +
    + +
    +

    Expected Impact for End-Users

    +
      +
    • + Contributors working with Codex repo instructions should see less duplicated policy in + AGENTS.md and clearer repo-only overrides. +
      • +
    • + Readers browsing project docs now have a dedicated anatomy reference page linked from the + docs index. +
      • +
    • + Once the external token is configured, GitHub Pages visitors should get the current docs + from dirtydishes.github.io/islandflow/docs/ instead of relying on a + mismatched branch target. +
      • +
    +
    + +
    +

    Validation

    +
      +
    • + Used git log scoped to May 31, 2026 to enumerate the three commits included + in this standup window. +
      • +
    • + Used git show --stat and targeted git show diffs to anchor the + changed files, workflow behavior, and visible Beads issue IDs for each commit. +
      • +
    • + For the docs mirror fix, reused validation already recorded in committed turn doc + 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. +
      • +
    • + No separate automated validation was visible in the inspected May 31 commits for the + AGENTS.md trim or the anatomy page beyond the committed file additions and + docs index linkage. +
      • +
    +
    + +
    +

    Issues, Limitations, and Mitigations

    +
    + commit-history only + token still required +
    +
      +
    • + This summary only reflects landed git history for May 31 and does not include uncommitted + work, discussion, or operational checks performed outside the repository. +
      • +
    • + The anatomy page commit did not include a companion turn document, so its validation + notes here are limited to what the commit itself showed: file creation, docs index update, + and Beads closure text. +
      • +
    • + The docs mirror workflow fix is not fully effective until the GitHub mirror repository + secret DOCS_PAGES_TOKEN is present and valid. That gap is already tracked in + islandflow-8a6. +
      • +
    +
    + +
    +

    Follow-up Work

    +
      +
    • + islandflow-8a6: verify the GitHub Pages token for the docs mirror so the + updated workflow can push to dirtydishes/dirtydishes.github.io. +
      • +
    • + No additional Beads follow-up was visible for the trimmed repo guidance commit + ab35533289b4 in the inspected history. +
      • +
    +
    +
    + + diff --git a/docs/index.html b/docs/index.html index 8e297ae..b511833 100644 --- a/docs/index.html +++ b/docs/index.html @@ -207,11 +207,11 @@
    -
    64 of 64 files shown
    +
    65 of 65 files shown
    @@ -651,9 +651,17 @@
    -

    general 6

    +

    general 7

      -
    • +
    • + general/2026-06-01-standup-summary-2026-05-31.html +
      + html + 17 KB + Jun 1, 2026, 9:04 AM +
      +
      • +
    • general/2026-05-29-standup-summary-2026-05-28.html
      html From 3a7267865219192159216cb35443dee68de66cc6 Mon Sep 17 00:00:00 2001 From: dirtydishes Date: Mon, 1 Jun 2026 09:46:23 -0400 Subject: [PATCH 4/4] harden docs pages publish --- .beads/issues.jsonl | 2 +- .github/workflows/docs-pages.yml | 1 + docs/index.html | 2 +- docs/turns/2026-05-31-fix-docs-pages-mirror.html | 8 ++++---- 4 files changed, 7 insertions(+), 6 deletions(-) diff --git a/.beads/issues.jsonl b/.beads/issues.jsonl index b896909..0b4c346 100644 --- a/.beads/issues.jsonl +++ b/.beads/issues.jsonl @@ -25,7 +25,7 @@ {"_type":"issue","id":"islandflow-ayo","title":"Drop stale backlog events from live fanout","description":"Follow-up to live freshness rollout: /ws/live was still fanning out stale backlog events for freshness-gated channels, which kept tape panes in Live feed behind despite active synthetic ingest. Gate fanout and cache ingest by freshness for options/nbbo/equities/flow.","status":"closed","priority":1,"issue_type":"bug","assignee":"dirtydishes","owner":"dishes@dpdrm.com","created_at":"2026-04-28T21:26:39Z","created_by":"dirtydishes","updated_at":"2026-04-28T21:26:44Z","started_at":"2026-04-28T21:26:44Z","closed_at":"2026-04-28T21:26:44Z","close_reason":"Completed","dependency_count":0,"dependent_count":0,"comment_count":0} {"_type":"issue","id":"islandflow-0v6","title":"Fix tape freshness, NBBO coverage, pause controls, and filter popup","description":"Implement the tape fixes requested for synthetic options notional sizing, strict live freshness, live-mode pause/resume behavior, stronger NBBO snapshot coverage, and moving flow filters behind a popup. Includes server-side live cache changes, web terminal state/UI changes, and tests for synthetic pricing, live snapshot freshness/NBBO retention, and live pause/filter interactions.","status":"closed","priority":1,"issue_type":"task","assignee":"dirtydishes","owner":"dishes@dpdrm.com","created_at":"2026-04-28T21:02:52Z","created_by":"dirtydishes","updated_at":"2026-04-28T21:13:38Z","started_at":"2026-04-28T21:02:57Z","closed_at":"2026-04-28T21:13:38Z","close_reason":"Completed","dependency_count":0,"dependent_count":0,"comment_count":0} {"_type":"issue","id":"islandflow-e4r","title":"Implement smart-money flow filtering and synthetic firehose modes","description":"Implement the approved multi-surface plan for named synthetic market profiles, options raw-vs-signal filtering, live/API filter contracts, Tape page client-side flow filters, firehose-readiness improvements, tests, and README updates.","status":"closed","priority":1,"issue_type":"feature","assignee":"dirtydishes","owner":"dishes@dpdrm.com","created_at":"2026-04-28T20:10:49Z","created_by":"dirtydishes","updated_at":"2026-04-28T20:29:29Z","started_at":"2026-04-28T20:10:53Z","closed_at":"2026-04-28T20:29:29Z","close_reason":"Implemented synthetic market profiles, options signal-path filtering, signal-aware API/replay contracts, Tape page filters, tests, and README updates. Follow-up tracked in islandflow-biq.","dependency_count":0,"dependent_count":0,"comment_count":0} -{"_type":"issue","id":"islandflow-8a6","title":"verify github pages token for docs mirror","description":"The docs mirror workflow now publishes islandflow/docs into dirtydishes/dirtydishes.github.io, but the GitHub Actions secret DOCS_PAGES_TOKEN must exist and have permission to push to that Pages repository. Verify the secret is configured and manually run the Publish Docs workflow after the mirror branch lands.","status":"open","priority":2,"issue_type":"task","owner":"dishes@dpdrm.com","created_at":"2026-05-31T22:12:27Z","created_by":"dirtydishes","updated_at":"2026-05-31T22:12:27Z","dependency_count":0,"dependent_count":0,"comment_count":0} +{"_type":"issue","id":"islandflow-8a6","title":"verify github pages token for docs mirror","description":"The docs mirror workflow now publishes islandflow/docs into dirtydishes/dirtydishes.github.io, but the GitHub Actions secret DOCS_PAGES_TOKEN must exist and have permission to push to that Pages repository. Verify the secret is configured and manually run the Publish Docs workflow after the mirror branch lands.","notes":"Direct manual publish to dirtydishes/dirtydishes.github.io succeeded on 2026-06-01 and https://dirtydishes.github.io/islandflow/docs/ returned HTTP 200. Remaining work is to verify DOCS_PAGES_TOKEN so the islandflow docs mirror workflow can publish future updates automatically.","status":"open","priority":2,"issue_type":"task","owner":"dishes@dpdrm.com","created_at":"2026-05-31T22:12:27Z","created_by":"dirtydishes","updated_at":"2026-06-01T13:45:34Z","dependency_count":0,"dependent_count":0,"comment_count":0} {"_type":"issue","id":"islandflow-5jt","title":"Add anatomy reference page","description":"Create a standalone docs/anatomy.html reference explaining how prints move through ingest, tape, flow packets, smart-money events, classifier hits, and alerts, including diagrams.","status":"closed","priority":2,"issue_type":"task","assignee":"dirtydishes","owner":"dishes@dpdrm.com","created_at":"2026-05-31T21:20:34Z","created_by":"dirtydishes","updated_at":"2026-05-31T21:25:54Z","started_at":"2026-05-31T21:20:44Z","closed_at":"2026-05-31T21:25:54Z","close_reason":"Added the standalone anatomy reference page and linked it from the docs index.","dependency_count":0,"dependent_count":0,"comment_count":0} {"_type":"issue","id":"islandflow-cig","title":"Expand CI quality gates","description":"Add a more robust CI workflow for the Bun/TypeScript monorepo, including formatting, linting, type checking, builds, and tests where appropriate.","status":"closed","priority":2,"issue_type":"task","assignee":"dirtydishes","owner":"dishes@dpdrm.com","created_at":"2026-05-30T06:29:33Z","created_by":"dirtydishes","updated_at":"2026-05-30T06:34:11Z","started_at":"2026-05-30T06:29:41Z","closed_at":"2026-05-30T06:34:11Z","close_reason":"Expanded CI quality gates with Biome formatting/linting, public API route checks, Docker snapshot validation, tests, typecheck, and web build validation.","dependency_count":0,"dependent_count":0,"comment_count":0} {"_type":"issue","id":"islandflow-3l6","title":"fix ci typecheck bun path resolution","description":"Forgejo CI fails in scripts/typecheck.ts because the script shells out to bunx, which expects bun on PATH. The runner installs Bun by absolute path, so the typecheck helper should use the current Bun executable instead of PATH lookup.","status":"closed","priority":2,"issue_type":"bug","assignee":"dirtydishes","owner":"dishes@dpdrm.com","created_at":"2026-05-30T05:34:55Z","created_by":"dirtydishes","updated_at":"2026-05-30T06:00:31Z","started_at":"2026-05-30T05:35:02Z","closed_at":"2026-05-30T06:00:31Z","close_reason":"Fixed the Forgejo CI terminal import mismatch by switching the terminal client component to a namespace import; verified locally and on Forgejo run #56.","dependency_count":0,"dependent_count":0,"comment_count":0} diff --git a/.github/workflows/docs-pages.yml b/.github/workflows/docs-pages.yml index 5fc6bcb..65df8fc 100644 --- a/.github/workflows/docs-pages.yml +++ b/.github/workflows/docs-pages.yml @@ -36,6 +36,7 @@ jobs: rm -rf site mkdir -p site/docs cp -R docs/. site/docs/ + find site -name .DS_Store -delete printf '%s\n' 'Islandflow DocsContinue to docs' > site/index.html touch site/.nojekyll diff --git a/docs/index.html b/docs/index.html index b511833..0e3ed60 100644 --- a/docs/index.html +++ b/docs/index.html @@ -224,7 +224,7 @@
      html 203 KB - May 31, 2026, 6:12 PM + Jun 1, 2026, 9:45 AM
    • diff --git a/docs/turns/2026-05-31-fix-docs-pages-mirror.html b/docs/turns/2026-05-31-fix-docs-pages-mirror.html index b065c76..a15c6e2 100644 --- a/docs/turns/2026-05-31-fix-docs-pages-mirror.html +++ b/docs/turns/2026-05-31-fix-docs-pages-mirror.html @@ -40,7 +40,7 @@
      May 31, 2026Beads: islandflow-m3dWorkflow: .github/workflows/docs-pages.yml

      Summary

      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.

      -

      Changes Made

      • Changed the workflow permission from write to read for the source repository, because publishing now happens through the target Pages checkout.
      • Added explicit Pages target settings for dirtydishes/dirtydishes.github.io, branch master, and prefix islandflow.
      • Added a target-repository checkout that uses secrets.DOCS_PAGES_TOKEN.
      • Mirrors the static payload into pages/islandflow/, which serves the docs at /islandflow/docs/.
      • Commits and pushes only when the generated mirror content actually changed.
      • Tightened the docs index generator so regenerated HTML does not introduce trailing whitespace.
      • Regenerated docs/index.html so the docs index reflects the current repository docs set.
      +

      Changes Made

      • Changed the workflow permission from write to read for the source repository, because publishing now happens through the target Pages checkout.
      • Added explicit Pages target settings for dirtydishes/dirtydishes.github.io, branch master, and prefix islandflow.
      • Added a target-repository checkout that uses secrets.DOCS_PAGES_TOKEN.
      • Mirrors the static payload into pages/islandflow/, which serves the docs at /islandflow/docs/.
      • Commits and pushes only when the generated mirror content actually changed.
      • Deletes .DS_Store files from the generated site payload before publishing.
      • Tightened the docs index generator so regenerated HTML does not introduce trailing whitespace.
      • Regenerated docs/index.html so the docs index reflects the current repository docs set.
      • Manually published the current docs snapshot to dirtydishes/dirtydishes.github.io while the automated mirror path awaits secret verification.

      Context

      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.

      Important Implementation Details

      • The public URL remains https://dirtydishes.github.io/islandflow/docs/.
      • The target repository branch is master, matching the current remote state of dirtydishes/dirtydishes.github.io.
      • The workflow removes and replaces only the islandflow/ subtree in the Pages repository, leaving any other site content alone.
      • The workflow requires a GitHub Actions secret named DOCS_PAGES_TOKEN with permission to read and write dirtydishes/dirtydishes.github.io.

      Relevant Diff Snippets

      Rendered with @pierre/diffs/ssr using server-side generated markup so this report is readable offline without loading remote JavaScript.

      128 unmodified lines
      129
      130
      131
      132
      133
      134
      135
      2 unmodified lines
      138
      139
      140
      141
      142
      143
      144
      145
      146
      147
      148
      149
      150
      151
      152
      153
      128 unmodified lines
      .map((entry) => {
      const extension = path.extname(entry.relativePath).replace(".", "") || "file";
      const searchable = `${entry.relativePath} ${category}`.toLowerCase();
      return ` <li class="doc-item" data-search="${escapeHtml(searchable)}">
      <a class="doc-link" href="${docsHref(entry.relativePath)}">${escapeHtml(
      entry.relativePath
      )}</a>
      2 unmodified lines
      <span>${escapeHtml(formatBytes(entry.sizeBytes))}</span>
      <span>${escapeHtml(dateFormatter.format(entry.modifiedAt))}</span>
      </div>
      </li>`;
      })
      .join("\n");
      return ` <section class="group" id="category-${escapeHtml(category)}">
      <h2>${escapeHtml(category)} <span>${entries.length}</span></h2>
      <ul class="doc-list">
      ${entryMarkup}
      </ul>
      </section>`;
      })
      .join("\n");
      -

      Expected Impact for End-Users

      Once the workflow runs on GitHub with DOCS_PAGES_TOKEN configured, readers should be able to browse the Islandflow docs at dirtydishes.github.io/islandflow/docs/ from the actual Pages site instead of depending on a missing or unconfigured project gh-pages branch.

      -

      Validation

      • Passed: Ran node scripts/generate-docs-index.mjs; it generated docs/index.html with 64 entries.
      • Passed: Ran node --check scripts/generate-docs-index.mjs.
      • Passed: Parsed .github/workflows/docs-pages.yml with Ruby YAML.
      • Passed: Ran git diff --check after tightening the generated index output.
      • Not completed: bunx actionlint .github/workflows/docs-pages.yml still failed because the package did not expose a runnable executable in this environment.
      -

      Issues, Limitations, and Mitigations

      • The workflow will fail until DOCS_PAGES_TOKEN exists in the GitHub mirror repository secrets and can push to dirtydishes/dirtydishes.github.io.
      • This was validated locally for generation and YAML syntax, but the cross-repository push itself can only be fully verified by a GitHub Actions run.
      • The docs index includes file modified timestamps, so regenerating it can change ordering and metadata when local mtimes differ from the committed version.
      +

      Expected Impact for End-Users

      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.

      +

      Validation

      • Passed: Ran node scripts/generate-docs-index.mjs; it generated docs/index.html with 65 entries.
      • Passed: Ran node --check scripts/generate-docs-index.mjs.
      • Passed: Parsed .github/workflows/docs-pages.yml with Ruby YAML.
      • Passed: Ran git diff --check after tightening the generated index output.
      • Passed: Published islandflow/docs to dirtydishes/dirtydishes.github.io and confirmed https://dirtydishes.github.io/islandflow/docs/ returns HTTP 200 with the docs index.
      • Not completed: bunx actionlint .github/workflows/docs-pages.yml still failed because the package did not expose a runnable executable in this environment.
      +

      Issues, Limitations, and Mitigations

      • The automated workflow will fail until DOCS_PAGES_TOKEN exists in the GitHub mirror repository secrets and can push to dirtydishes/dirtydishes.github.io.
      • The live site is currently repaired by a direct Pages repository publish; the workflow still needs a real GitHub Actions run after secret verification.
      • The docs index includes file modified timestamps, so regenerating it can change ordering and metadata when local mtimes differ from the committed version.

      Follow-up Work

      • 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.
      • Consider replacing timestamp-based docs index ordering with commit dates or filenames so generated output is less sensitive to local filesystem mtimes.