toga-ai 1.0.626 → 1.0.628

package/knowledge/2.0/apps/toga-blox/INDEX.md

@@ -10,4 +10,5 @@
 | [Primary Table templates (server/client, sizing, virtualization)](features/primary-table-templates.md) | `src/templates/PrimaryTable/` is the **production, wired-up table** built on the [Table component](table.md). | toga-blox/src/templates/PrimaryTable/PrimaryTable.tsx, toga-blox/src/templates/PrimaryTable/PrimaryTableServerTemplate.tsx, toga-blox/src/templates/PrimaryTable/PrimaryTableClientTemplate.tsx, toga-blox/src/templates/PrimaryTable/PrimaryTableHeaderCell.tsx, toga-blox/src/templates/PrimaryTable/PrimaryTableBodyCell.tsx, toga-blox/src/templates/PrimaryTable/PrimaryTableRow.tsx, toga-blox/src/templates/PrimaryTable/PrimaryTableExpandableRow.tsx, toga-blox/src/templates/PrimaryTable/types.ts |
 | [TableRecordModal (record-detail modal shell)](features/table-record-modal.md) | `TableRecordModal` is a **generic, presentational modal shell** for showing a single table record (row) in detail — typically opened from a table row click. | toga-blox/src/components/TableRecordModal/TableRecordModal.tsx, toga-blox/src/components/TableRecordModal/index.ts, toga-blox/src/components/TableRecordModal/tableRecordModal.module.css |
 | [Table component (cells, action cells, filters & sorts, hooks, theming)](features/table.md) | The `Table` component (`src/components/Table/`) is the **TanStack Table v8** building block behind the [Primary Table templates](primary-table-templates.md). | toga-blox/src/components/Table/index.ts, toga-blox/src/components/Table/types.ts, toga-blox/src/components/Table/utils/buildTanstackColumns.tsx, toga-blox/src/components/Table/utils/resolveCellType.tsx, toga-blox/src/components/Table/components/cellTypes, toga-blox/src/components/Table/components/actionCells, toga-blox/src/components/Table/components/columnFiltersAndSorts, toga-blox/src/components/Table/hooks, toga-blox/src/components/Table/themeConfig |
+| [Talos AI-Assistant Component (launcher + slide-out chat panel)](features/talos-assistant.md) | `Talos` is a **shared, pure-UI** AI-assistant component in `@agilant/toga-blox`: a header launcher button (`TalosLauncher`) plus a slide-out chat panel (`TalosP | toga-blox/src/components/Talos/TalosLauncher.tsx, toga-blox/src/components/Talos/TalosPanel.tsx, toga-blox/src/components/Talos/TalosMessage.tsx, toga-blox/src/components/Talos/types.ts, toga-blox/src/components/Talos/theme.ts, toga-blox/src/components/Talos/helpers.tsx, toga-blox/src/components/Talos/stub.ts, toga-blox/src/components/Talos/Talos.module.css, toga-blox/src/components/Talos/index.ts, toga-blox/src/components/index.ts |
 | [Dynamic npm Publish Pipeline (branch → channel)](workflows/dynamic-publish-pipeline.md) | How `@agilant/toga-blox` (checkout folder `toga-blox-npm`, registry repo key `toga-blox`) publishes a per-environment npm **channel** (dist-tag) from a `_<mode> | toga-blox/.github/workflows/publish.yml, toga-blox/package.json, toga-blox/src/utils/getFontAwesomeIcon.tsx |

package/knowledge/2.0/apps/toga-blox/features/talos-assistant.md

@@ -0,0 +1,86 @@
+---
+title: Talos AI-Assistant Component (launcher + slide-out chat panel)
+framework: "2.0"
+repo: toga-blox
+project: TOGa Blox
+client: shared
+type: feature
+status: active
+updated: 2026-08-20
+owners: [apeterson]
+files:
+  - toga-blox/src/components/Talos/TalosLauncher.tsx
+  - toga-blox/src/components/Talos/TalosPanel.tsx
+  - toga-blox/src/components/Talos/TalosMessage.tsx
+  - toga-blox/src/components/Talos/types.ts
+  - toga-blox/src/components/Talos/theme.ts
+  - toga-blox/src/components/Talos/helpers.tsx
+  - toga-blox/src/components/Talos/stub.ts
+  - toga-blox/src/components/Talos/Talos.module.css
+  - toga-blox/src/components/Talos/index.ts
+  - toga-blox/src/components/index.ts
+related:
+  - ../architecture.md
+  - ../workflows/dynamic-publish-pipeline.md
+  - ../../toga25-supply/features/talos-integration.md
+---
+
+## Summary
+
+`Talos` is a **shared, pure-UI** AI-assistant component in `@agilant/toga-blox`: a header
+launcher button (`TalosLauncher`) plus a slide-out chat panel (`TalosPanel`) with two
+presentations — **docked** (resizable right rail) and **expanded** (centered modal + scrim).
+Ported from a TOGa Desk prototype and intended for reuse across toga25-supply, toga2-desk,
+and toga2-commerce. Build once, retheme per app. (TRUE-80692)
+
+The defining constraint: the component holds **no business logic and no `window.*` globals** —
+every side effect flows through an injected adapter, and every visual token is overridable.
+The real chat backend is a **later ticket**; `onSend` currently ships stubbed.
+
+## Architecture (the four load-bearing decisions)
+
+- **Pure UI + injected adapter.** All side effects go through an injected `TalosAdapter`:
+  `onSend(text) => Promise<TalosResponse>`, `onOpenRecord(id)`, `onAction(key)`,
+  `onDockWidthChange(px)`, `onAttach()`. The host owns everything. `createTalosStubAdapter()`
+  ships for backend-free/demo use (stubbed `onSend` this ticket).
+- **Controlled state.** `open` / `expanded` / `width` are controlled props owned by the host
+  (`onOpenChange` / `onExpandedChange` / `onWidthChange`); the component never manages them
+  internally.
+- **Fully tokenized styling.** Every color/font-size/weight/line-height/radius/shadow/dimension
+  is a `var(--talos-*, default)` custom property. `Talos.module.css` **is** the default theme
+  (the TOGa pink look). No forced Google-Fonts `@import` inside the shared component — the host
+  loads the font; default family is "Plus Jakarta Sans".
+- **Theme override model.** A typed `TalosTheme` object (`theme.ts`) + `talosThemeToVars()`
+  converter is passed as an optional `theme` prop on `TalosLauncher`/`TalosPanel`; it emits
+  `--talos-*` inline overrides on the root elements. Unset keys fall through to defaults.
+  Because the CSS is all `var()` fallbacks, **any** `--talos-*` token is also overridable via
+  host CSS on an ancestor — not just the typed subset.
+
+Reuses blox `BaseToolTip` + `getFontAwesomeIcon` (icon names are camelCase FA names).
+
+## Theming ceiling (known design boundary)
+
+**Themeable today:** full palette, font, dock/expanded dimensions, launcher size, radii,
+shadows, orbit/blob/gradient/scrim decoration, launcher icon image (via `branding.avatarSrc`),
+and content props (suggestions / greeting / subtitle / placeholder / disclaimer / statusColors /
+branding name+initials).
+
+**NOT themeable yet:** internal **spacing/density** — ~38 padding/gap/margin values remain raw
+literals, so apps can recolor and narrow the panel but cannot make it denser/compact (relevant
+for a small TOGa Desk side chat). Genuinely different **layouts** (e.g. pill launcher vs icon
+button, dropping expanded mode) are variants, not theme overrides.
+
+**Proposed future work (NOT done):** a spacing-token pass and/or a `density` preset prop
+(`"comfortable" | "compact"`), and possibly a launcher `variant` + optional panel-mode props.
+Open questions were handed to the UX/UI team.
+
+## Gotchas
+
+- The real chat backend is a later ticket — `onSend` is stubbed; do not assume live responses.
+- blox `dist` is gitignored (shipped via publish, not the branch). Other consumers only get
+  Talos after blox is **published** per the `_sandbox-dev` dist-tag workflow — see
+  [Dynamic npm Publish Pipeline](../workflows/dynamic-publish-pipeline.md). toga25-supply
+  currently consumes it via a local symlink.
+
+## Change history
+- 2026-08-20 — Built Talos shared AI-assistant component (launcher + docked/expanded chat panel): pure-UI + injected `TalosAdapter`, controlled open/expanded/width, fully `--talos-*` tokenized styling with typed `TalosTheme` overrides, stub adapter. Two adversarial review passes hardened it (removed a `window.dispatchEvent("resize")` side channel and a hardcoded initials literal; moved resize into an effect with cleanup + rAF throttle + keyboard `role="separator"`; SSR-safe portal guard; memoized message/handlers; restored the attach button + 11px card radius). Documented the spacing/density theming ceiling as future work (apeterson).

package/knowledge/2.0/apps/toga25-supply/INDEX.md

@@ -11,5 +11,6 @@
 | [Meta-Driven Page & Table Setup](features/meta-driven-table-data.md) | A page in this app is **meta-driven end to end**: the page view model fetches *page meta* (labels, sections, ACL) and *table meta* (the columns/fields + table s | toga25-supply/src/pages/SalesOrders/viewModel/useSalesOrdersPageViewModel.tsx, toga25-supply/src/pages/SalesOrders/hooks/useSalesOrdersTableState.ts, toga25-supply/src/hooks/useTablePageMeta.ts, toga-blox-npm/dist/hooks/useFetchPageMeta.d.ts, toga-blox-npm/dist/hooks/useFetchTablePageMeta.d.ts, toga-blox-npm/dist/hooks/useAssignTableFieldLabels.d.ts, toga-blox-npm/dist/components/Table/hooks/useTableData.d.ts |
 | [Record Modals & Nested Tables](features/record-modals-and-nested-tables.md) | The repo's family of modal + nested-table patterns layered over toga-blox `TableRecordModal` and `PrimaryTable*Layout`. | toga25-supply/src/layout/PrimaryTableServerLayout/PrimaryTableServerLayout.tsx, toga25-supply/src/layout/PrimaryTableServerLayout/types.ts, toga25-supply/src/layout/ItemRecordModalLayout/, toga25-supply/src/layout/SalesOrderRecordModalLayout/, toga25-supply/src/layout/SalesOrderItemsTableLayout/, toga25-supply/src/layout/ItemFulfillmentModal/, toga25-supply/src/layout/GenericNestedTables/GenericNestedTables.tsx, toga25-supply/src/layout/GenericNestedTables/GenericTableLayout.tsx, toga25-supply/src/pages/Inventory/viewModel/useInventoryPageViewModel.tsx, toga25-supply/src/pages/Inventory/viewModel/FIELDS/DEFAULT/inventoryGroupings.json, toga25-supply/src/hooks/useTableCellInteractions.ts, toga25-supply/src/hooks/useServerTableUrlState.ts, toga25-supply/src/layout/RecordApprovalModal/helpers/handleFormatApprovalWorkflowPayload.ts, toga25-supply/src/layout/RecordApprovalModal/api/approvalDecisionsApi.ts |
 | [Surface Frontend (DB-driven UI consumption, src/surface/)](features/surface-frontend.md) | The frontend consumer of the platform-wide Surface layer — DB-driven UI config fetched from `GET /v2/surfaces/meta?slug=<slug>` instead of statically-imported J | toga25-supply/src/surface/applyColSpan.ts, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/helpers/sectionRenderers.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/helpers/getVisibleSections.ts, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/layoutComponents/SalesOrderApprovalSummaryGrid.tsx, toga25-supply/src/surface/useFetchSurfaceMeta.ts, toga25-supply/src/pages/SalesOrders/helpers/surfaceBundleToTenantFields.ts, toga25-supply/src/pages/SalesOrders/helpers/buildPatchedTenantFields.ts, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/viewModel/useSalesOrderRecordModalLayoutModel.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/SalesOrderView.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/layoutComponents/SalesOrderSummaryGrid.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/helpers/getDetailSections.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/sections/SalesOrderNotesSection.tsx, toga25-supply/src/pages/SalesOrders/helpers/cleanOrder.ts, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/sections/AdminNotesSection.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/helpers/getAdminNotes.ts, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/helpers/index.ts, toga25-supply/src/surface/evaluateSurfaceRule.ts, toga25-supply/src/surface/resolveElementState.ts, toga25-supply/src/pages/SalesOrders/helpers/evaluateEnableRule.ts, toga25-supply/src/pages/SalesOrders/hooks/useSalesOrderRowRecordState.ts, toga25-supply/src/surface/actionRegistry.ts, toga25-supply/src/surface/componentRegistry.tsx, toga25-supply/src/surface/SurfaceActionBar.tsx, toga25-supply/src/surface/SurfaceSection.tsx, toga25-supply/src/surface/resolve.ts, toga25-supply/src/surface/types.ts, toga25-supply/src/surface/index.ts, toga25-supply/src/pages/Login/LoginPage.tsx, toga25-supply/src/pages/SalesOrders/SalesOrders.tsx, toga25-supply/src/pages/SalesOrders/view/SurfaceRowActions.tsx, toga25-supply/src/pages/SalesOrders/hooks/useSalesOrderVip.ts, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/sections/SalesOrderTopBar.tsx, toga25-supply/src/pages/Items/ItemsPage.tsx, toga25-supply/src/pages/Items/viewModel/useItemsPageViewModel.tsx, toga25-supply/src/pages/VendorItems/VendorItemsPage.tsx, toga25-supply/src/pages/VendorItems/viewModel/useVendorItemsPageViewModel.tsx, toga25-supply/src/pages/Inventory/Inventory.tsx, toga25-supply/src/pages/Inventory/viewModel/useInventoryPageViewModel.tsx, toga25-supply/src/pages/Inventory/viewModel/FIELDS/index.ts, toga25-supply/src/fieldsConfig/index.ts, toga25-supply/src/layout/ItemRecordModalLayout/helpers/surfaceBundleToItemFields.ts, toga25-supply/src/layout/ItemRecordModalLayout/helpers/index.ts, toga25-supply/src/layout/ItemRecordModalLayout/viewModel/useItemRecordModalViewModel.tsx, toga25-supply/src/layout/ItemRecordModalLayout/ItemRecordModalLayout.tsx, toga25-supply/src/layout/ItemRecordModalLayout/components/ItemRecordView.tsx, toga25-supply/src/surface/useStatusColors.ts, toga25-supply/src/surface/SurfaceHeader.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderApprovalModalsLayout/helpers/surfaceBundlesToDecisionFields.ts, toga25-supply/src/pages/SalesOrders/view/SalesOrderApprovalModalsLayout/viewModel/useApprovalModalViewModel.tsx |
+| [Talos Integration (AppLayout host + adapter wiring)](features/talos-integration.md) | toga25-supply is the first host of the shared blox [Talos assistant](../../toga-blox/features/talos-assistant.md). | toga25-supply/src/layout/AppLayout/AppLayout.tsx, toga25-supply/src/components/Header/Header.tsx, toga25-supply/src/components/Header/Header.module.css, toga25-supply/src/index.css, toga25-supply/src/assets/talos-owl.png |
 | [AWS Amplify Multi-Environment Deployment](workflows/amplify-deployment.md) | How `toga25-supply` deploys to **all** of its environments on AWS Amplify from a **single shared `amplify.yml`**. | toga25-supply/amplify.yml, toga25-supply/src/api/api.ts, toga25-supply/src/hooks/useAuthenticationFlow.ts, toga25-supply/vite.config.ts, toga25-supply/package.json |
 | [Cypress Testing Harness (component + e2e)](workflows/cypress-testing.md) | The Cypress test harness for the `toga25-supply` frontend, bootstrapped from scratch (`cypress` was already a dependency but there was no config, no `cypress/` | toga25-supply/cypress.config.ts, toga25-supply/cypress/tsconfig.json, toga25-supply/cypress/support/component.tsx, toga25-supply/cypress/support/component-index.html, toga25-supply/cypress/support/e2e.ts, toga25-supply/cypress/support/commands.ts, toga25-supply/cypress/support/fixtures.ts, toga25-supply/cypress/support/mocks/useApprovalModalViewModel.ts, toga25-supply/cypress/component/SalesOrderApprovalModalsLayout.cy.tsx, toga25-supply/cypress/component/RecordApprovalModalLayout.cy.tsx, toga25-supply/cypress/component/EnterPoNumberModal.cy.tsx, toga25-supply/cypress/e2e/salesOrderApproval.cy.ts |

package/knowledge/2.0/apps/toga25-supply/features/talos-integration.md

@@ -0,0 +1,52 @@
+---
+title: Talos Integration (AppLayout host + adapter wiring)
+framework: "2.0"
+repo: toga25-supply
+project: TOGa 2.5 Supply
+client: shared
+type: feature
+status: active
+updated: 2026-08-20
+owners: [apeterson]
+files:
+  - toga25-supply/src/layout/AppLayout/AppLayout.tsx
+  - toga25-supply/src/components/Header/Header.tsx
+  - toga25-supply/src/components/Header/Header.module.css
+  - toga25-supply/src/index.css
+  - toga25-supply/src/assets/talos-owl.png
+related:
+  - ../../toga-blox/features/talos-assistant.md
+---
+
+## Summary
+
+toga25-supply is the first host of the shared blox [Talos assistant](../../toga-blox/features/talos-assistant.md).
+**Enabled for ALL clients (no per-client gating).** `AppLayout` is the host: it owns Talos
+state and injects the adapter; the launcher renders in the header, the panel at app root.
+(TRUE-80693)
+
+## How it works
+
+- **AppLayout owns the state** — `open` / `expanded` / `width` / `dockWidth` — and injects the
+  adapter:
+  - `onSend`: stub (real backend is a later blox ticket).
+  - `onOpenRecord(id)` → navigate `/sales-orders?sales-orders=<id>`.
+  - `onAction("approvals")` → navigate `/sales-orders`.
+  - `onDockWidthChange(px)` → reserve layout width for the docked panel.
+- **Rendering** — `<TalosLauncher>` renders in the header via a new presentational
+  `talosLauncher` slot prop on the blox `Header` component, laid out through a `.headerActions`
+  flex wrapper. `<TalosPanel>` renders at app root.
+- **Branding/font** — the owl asset (`src/assets/talos-owl.png`) is passed as
+  `branding.avatarSrc`; Plus Jakarta Sans is loaded in `src/index.css` (the shared component
+  does not import fonts itself).
+
+## Gotcha — reserve dock width on the OUTER wrapper, not just `<main>`
+
+The docked panel is `position: fixed`, full-height on the right. The blox `Header` is in
+**normal document flow** (NOT fixed). Reserving the dock width only on `<main>` leaves the
+header's right edge sitting **under** the panel, hiding the launcher + avatar. **Fix:** apply
+the reserved dock width (`marginRight` = the `onDockWidthChange` value) to the **outer app
+wrapper** so the header shifts along with the content.
+
+## Change history
+- 2026-08-20 — Wired the shared blox Talos assistant into supply for all clients: AppLayout hosts state + injects the adapter (stub `onSend`; `onOpenRecord`/`onAction` navigate to sales orders; `onDockWidthChange` reserves layout width), launcher in a new header `talosLauncher` slot, panel at app root, owl avatar + Plus Jakarta Sans loaded locally. Fixed the docked panel hiding the header launcher by reserving dock width on the outer wrapper (apeterson).

package/knowledge/2.0/apps/worker2/INDEX.md

@@ -35,7 +35,7 @@
 | [DB-Driven Notification (Internal) Email](features/notification-email.md) | Internal/notification emails (merge-conflict alerts, ops notices — anything system-generated, not client-facing transactional mail) are sent through one worker | worker2/Worker/Notification/Email.php, _underscore/Model/Client/EmailTemplate.php, dbchanges2/Client/2026-06-23a - EmailTemplateWrapper.sql, dbchanges2/Client_True/2026-06-23a - EmailTemplateWrapper.sql |
 | [NYCHH Asset-Tag Backfill (worker2)](features/nychh-asset-tag-backfill.md) | Keeps NYC Health & Hospitals (`Client_Nychh`) unit asset tags and MAC addresses synced from NetSuite. | worker2/Worker/Client/Nychh.php, worker2/Worker/Client/Nychh/AssetTagBackfill.php, worker/crons/toga2/netsuite/verify_fulfillment_asset_tag_sync_nychh.php, worker/crons/toga2/netsuite/backfill_all_asset_tags_from_netsuite_nychh.php |
 | [OneUptime Incident → ClickUp Task Sync (Monitor/Oneuptime/SyncIncidents)](features/oneuptime-incident-clickup-sync.md) | An internal/shared TOGA ops feature: worker2 polls the OneUptime API every 15 minutes for **currently-open** incidents and ensures a ClickUp task exists for eac | worker2/Component/Api/Oneuptime/Oneuptime.php, worker2/Worker/Monitor/Oneuptime.php, worker2/Config/production.ini, dbchanges2/Team/2026-08-10a - OneUptime Incident ClickUp Tasks.sql, dbchanges2/Core/2026-08-10b - OneUptime Incident Sync CronJob.sql, dbchanges2/Team/2026-08-12a - OneUptime Incident Tasks Closed Marker.sql |
-| [OneUptime push-metric monitors for 2.0 workers](features/oneuptime-worker2-monitoring.md) | A second, **OneUptime-reporting** monitoring pattern for the 2.0 worker2 tier, ported from the 1.0 `App_SystemMonitor_Compass` monitors. | worker2/Worker/Monitor/Compass.php, worker2/Worker/Client/Compass.php, worker2/composer.json, _underscore/Cloud.php, worker2/Worker/Monitor/Operations.php, worker2/Worker/Monitor/Aig.php, worker2/Worker/Monitor/Prudential.php, worker2/Worker/Monitor/Nycdoe.php, worker2/Config/production.ini, worker2/Config/beta.ini, worker2/Config/sandbox-dev.ini |
+| [OneUptime push-metric monitors for 2.0 workers](features/oneuptime-worker2-monitoring.md) | A second, **OneUptime-reporting** monitoring pattern for the 2.0 worker2 tier, ported from the 1.0 `App_SystemMonitor_Compass` monitors. | worker2/Worker/Monitor/Compass.php, worker2/Worker/Client/Compass.php, worker2/composer.json, _underscore/Cloud.php, worker2/Worker/Monitor/Operations.php, worker2/Worker/Monitor/Aig.php, worker2/Worker/Monitor/Prudential.php, worker2/Worker/Monitor/Nycdoe.php, worker2/Worker/Monitor/Staples.php, worker2/Config/production.ini, worker2/Config/beta.ini, worker2/Config/sandbox-dev.ini |
 | [Platform Cache Cleanup (_Worker_Platform_Cache — Clean + Truncate)](features/platform-cache-cleanup.md) | `_Worker_Platform_Cache` owns maintenance of the shared **Cache** cluster that backs api2's [multi-client data retrieval](../../api2/features/cross-client-data- | worker2/Worker/Platform/Cache.php, worker2/Controller/Index.php, worker2/_.php, dbchanges2/Core/2026-07-27a - PlatformCacheCleanCron.sql |
 | [Service Request → Sales Order → Purchase Order generation (Sync/ServiceRequest)](features/service-request-sales-order-generation.md) | `_Worker_Sync_ServiceRequest` turns a **Service Request into a Sales Order, and then into one Purchase Order per vendor**, for **any** tenant. | worker2/Worker/Sync/ServiceRequest.php, _underscore/Model/Elite/ServiceRequest.php, dbchanges2/Core/2026-08-06a - Service request and sales order payload interceptors.sql |
 | [Startech Webhook Handler (worker2)](features/startech-webhook-handler.md) | Receives inbound webhook events from Startech (Easeedesk) and creates or updates the corresponding ticket in TOGA 2.0. | worker2/Worker/Startech.php |

package/knowledge/2.0/apps/worker2/features/oneuptime-worker2-monitoring.md

@@ -6,8 +6,8 @@ project: Worker
 client: shared
 type: feature
 status: active
-updated: 2026-08-17
-owners: ["jcardinal", "mhammontree"]
+updated: 2026-08-20
+owners: ["jcardinal", "mhammontree", "bala"]
 files:
   - worker2/Worker/Monitor/Compass.php
   - worker2/Worker/Client/Compass.php
@@ -17,6 +17,7 @@ files:
   - worker2/Worker/Monitor/Aig.php
   - worker2/Worker/Monitor/Prudential.php
   - worker2/Worker/Monitor/Nycdoe.php
+  - worker2/Worker/Monitor/Staples.php
   - worker2/Config/production.ini
   - worker2/Config/beta.ini
   - worker2/Config/sandbox-dev.ini
@@ -26,6 +27,7 @@ related:
   - ./all-client-email-queue-monitor.md
   - ../../_underscore/features/cloud-s3-helpers.md
   - ../../../1.0/apps/worker/features/oneuptime-worker-uptime-monitoring.md
+  - ../../../clients/staples/features/oneuptime-sftp-folder-monitors.md
 ---
 
 ## Summary
@@ -255,6 +257,38 @@ relies on it) — no new Entra consent.
   worker EB tier. The `client_secret` is a credential — it lives in the ini config group,
   never in a doc.
 
+## SFTP monitoring (phpseclib3)
+
+An SFTP monitor logs into an SFTP with **phpseclib3**, `rawlist`s a folder, counts files
+older than an age cutoff, and pushes a decided alarm token — the same reporter model as the
+S3/DB monitors. A login/list failure pushes `status:"error"`, so the monitor doubles as an
+SFTP connectivity check. First instance:
+[Staples SFTP folder monitors](../../../clients/staples/features/oneuptime-sftp-folder-monitors.md).
+
+Two runtime facts about the installed phpseclib3 (v3.0.49) that bite silently — verified at
+runtime against the live SFTP:
+
+- **`SFTP::rawlist($dir)` (non-recursive) returns each entry as an associative ARRAY**, not
+  a stdClass object — keys `'type'`, `'mtime'`, `'filename'`, `'size'`, … Object access
+  (`$entry->mtime`) silently fails. Use array access: `$entry['mtime']`, `$entry['type']`.
+- **The SFTP file-type constants are NOT defined at class-load.** Neither the class const
+  `SFTP::TYPE_DIRECTORY` nor the global `NET_SFTP_TYPE_DIRECTORY` exists when you just
+  load/use the class (phpseclib defines the globals lazily); `defined()` returned false for
+  both. Compare `type` against the SFTP-protocol numeric value via a **self-defined
+  constant**: `1` = regular file, `2` = directory. (`rawlist` returned php-type=array,
+  `type=1` for files, and `mtime` as a unix epoch matching the filename timestamp.)
+
+**Symptom when either is wrong:** reads guarded by `isset()`/`??` silently make the aged-file
+count always **0**, so the monitor never alarms and reads as perfectly healthy. Test the
+count against a folder you know has aged files.
+
+### `_Config::<group>('key')` throws on a missing key — pass a falsy fallback
+
+`_Config::<group>('key')` **throws** when the key is absent, so a `?:` default after it is
+dead code. To get a safe fallback, pass a **falsy second argument**:
+`_Config::sftp_staples('port', false) ?: 22`. Without the second arg the `?:` never runs
+because the throw happens first.
+
 ## Composer / deploy dependency
 
 `worker2/composer.json` added `javanile/php-imap2` (`^0.1.10`) for the IMAP path. The
@@ -293,6 +327,13 @@ check for another client.
   monitors must pass the region (see [Cloud S3 helpers](../../_underscore/features/cloud-s3-helpers.md)).
 
 ## Change history
+- 2026-08-20 — Added the **SFTP monitor** shape (phpseclib3 `rawlist` + age-cutoff count +
+  decided token; login/list failure → `status:error` connectivity check) and its two
+  runtime gotchas: `rawlist` returns **arrays** not objects, and the SFTP type constants are
+  **not defined at class-load** (use a self-defined `1`=file/`2`=dir). Also recorded that
+  `_Config::<group>('key')` **throws** on a missing key — pass a falsy 2nd arg for a `?:`
+  fallback. First instance:
+  [Staples SFTP folder monitors](../../../clients/staples/features/oneuptime-sftp-folder-monitors.md). (bala)
 - 2026-08-17 — TRUE-80587: added five monitors and generalized this doc beyond Compass —
   `Monitor/Prudential/{SalesOrderGenerationBacklog,DellPurchaseOrderTransmissionBacklog,
   OrderShippedUpdateBacklog}`, `Monitor/Aig/EntitlementApiHealth`,

package/knowledge/INDEX.md

@@ -19,7 +19,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 ## 2.0 framework
 
 - **_underscore** (_Underscore) _(framework core)_ — 61 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
-- **worker2** (Worker) — 53 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
+- **worker2** (Worker) — 54 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
 - **api2** (API) — 25 doc(s) → [2.0/apps/api2/INDEX.md](2.0/apps/api2/INDEX.md)
 - **dbchanges2** (Database Changes) _(framework core)_ — 8 doc(s) → [2.0/apps/dbchanges2/INDEX.md](2.0/apps/dbchanges2/INDEX.md)
 - **toga2-supply** (TOGa Supply) — 7 doc(s) → [2.0/apps/toga2-supply/INDEX.md](2.0/apps/toga2-supply/INDEX.md)
@@ -30,8 +30,8 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 - **voice-to-voice** (TOGa Voice) — 4 doc(s) → [2.0/apps/voice-to-voice/INDEX.md](2.0/apps/voice-to-voice/INDEX.md)
 - **ai-bdr** (AI-BDR) — 9 doc(s) → [2.0/apps/ai-bdr/INDEX.md](2.0/apps/ai-bdr/INDEX.md)
 - **toga2-commerce** (TOGa Commerce) — 19 doc(s) → [2.0/apps/toga2-commerce/INDEX.md](2.0/apps/toga2-commerce/INDEX.md)
-- **toga25-supply** (TOGa 2.5 Supply) — 11 doc(s) → [2.0/apps/toga25-supply/INDEX.md](2.0/apps/toga25-supply/INDEX.md)
-- **toga-blox** (TOGa Blox) — 9 doc(s) → [2.0/apps/toga-blox/INDEX.md](2.0/apps/toga-blox/INDEX.md)
+- **toga25-supply** (TOGa 2.5 Supply) — 12 doc(s) → [2.0/apps/toga25-supply/INDEX.md](2.0/apps/toga25-supply/INDEX.md)
+- **toga-blox** (TOGa Blox) — 10 doc(s) → [2.0/apps/toga-blox/INDEX.md](2.0/apps/toga-blox/INDEX.md)
 - **bdr** (BDR) — 0 doc(s) → [2.0/apps/bdr/INDEX.md](2.0/apps/bdr/INDEX.md)
 
 ## standalone framework

package/knowledge/clients/staples/INDEX.md

@@ -2,4 +2,5 @@
 
 | Doc | Framework | Summary | Files |
 |-----|-----------|---------|-------|
+| [Staples: OneUptime SFTP folder monitors (Monitor/Staples/*)](features/oneuptime-sftp-folder-monitors.md) | 2.0 | Two worker2 OneUptime push monitors that watch the **Staples SFTP** for stuck files in either direction — a backlog that previously had **no alerting** (the ear | worker2/Worker/Monitor/Staples.php, worker2/Config/beta.ini, worker2/Config/production.ini, dbchanges2/Core/2026-08-20a - Staples SFTP Monitors.sql |
 | [Staples](profile.md) | 1.0 | Staples is a **headless** integration client — no UI, Worker 1.0 only, depending on the `library` (1.0 `App_`) core. | worker/crons/sync/staples/sync_staples_cxml.php, worker/crons/sync/staples/staples_asn_netsuite.php |

package/knowledge/clients/staples/features/oneuptime-sftp-folder-monitors.md

@@ -0,0 +1,113 @@
+---
+title: "Staples: OneUptime SFTP folder monitors (Monitor/Staples/*)"
+framework: "2.0"
+repo: worker2
+project: Worker
+client: staples
+type: client-feature
+status: active
+updated: 2026-08-20
+owners: ["bala"]
+files:
+  - worker2/Worker/Monitor/Staples.php
+  - worker2/Config/beta.ini
+  - worker2/Config/production.ini
+  - dbchanges2/Core/2026-08-20a - Staples SFTP Monitors.sql
+related:
+  - ../../../2.0/apps/worker2/features/oneuptime-worker2-monitoring.md
+  - ../profile.md
+  - ../../../1.0/apps/worker/features/staples-cxml-order-import.md
+---
+
+## Summary
+
+Two worker2 OneUptime push monitors that watch the **Staples SFTP** for stuck files in
+either direction — a backlog that previously had **no alerting** (the earlier `/out` pickup
+pileup incident went unnoticed). They implement the shared pattern in
+[OneUptime push-metric monitors for 2.0 workers](../../../2.0/apps/worker2/features/oneuptime-worker2-monitoring.md);
+read that first for the payload contract, criteria set, and provisioning runbook.
+
+- `Monitor/Staples/InboundOrderQueue` — watches **`/in`** (cXML orders Staples sent that
+  TOGA has not yet imported).
+- `Monitor/Staples/OutboundPickupQueue` — watches **`/out`** (855 acknowledgements + 856
+  ASNs TOGA wrote, waiting for Staples to download).
+
+Because each monitor logs into SFTP and lists a folder, it **doubles as an SFTP
+connectivity check**: a login/list failure pushes `status:"error"`, so a dead checker or a
+broken SFTP is distinguishable from a real backlog.
+
+## Key files / entry points
+
+- `worker2/Worker/Monitor/Staples.php` — `abstract class _Worker_Monitor_Staples`; two
+  `public static` action methods (`InboundOrderQueue`, `OutboundPickupQueue`), each
+  self-contained (in-method `ALL_CAPS` locals + `$push` closure), following the shared
+  "dumb reporter, smart monitor" model.
+- `dbchanges2/Core/2026-08-20a - Staples SFTP Monitors.sql` — the two `Core.CronJobs` rows
+  (actions `Monitor/Staples/InboundOrderQueue` and `Monitor/Staples/OutboundPickupQueue`,
+  schedule `*/5 * * * *`, `maxExecutionTime` 120), following the sibling monitor
+  cron-registration migration pattern.
+- `[sftp_staples]` config group in `worker2/Config/beta.ini` and
+  `worker2/Config/production.ini` — SFTP host/port/user/password. **The password is a
+  credential; it lives only in the ini group, never in this doc.**
+
+## How it works
+
+Each monitor logs into the Staples SFTP with **phpseclib3**, `rawlist`s the target folder,
+counts files older than an age threshold, decides an alarm token (`HIGH`/`OK`), and POSTs
+the JSON body to a OneUptime incoming-request monitor. The worker makes the threshold
+decision; OneUptime only string-matches the token (it cannot compare numbers — see the
+shared doc). The OneUptime push URLs are in-file constants (push credentials — never logged
+or recorded).
+
+### Staples SFTP folder semantics (background for the thresholds)
+
+The Staples pipeline runs in the **1.0 `worker`** tier, not worker2; worker2 only watches
+the folders. The relevant 1.0 crons and folder meanings (schedules are in
+`worker/schedules/cron.worker.sync.json`, in the server's **Central** timezone):
+
+| 1.0 cron | Schedule | What it does |
+|---|---|---|
+| `worker/crons/sync/staples/sync_staples_cxml.php` | `45 * * * *` (hourly) | imports Staples cXML orders from `/in` into NetSuite, writes an 855 ack to `/out`, archives the processed inbound file to `/archive/archive_in` |
+| `worker/crons/sync/staples/staples_asn_netsuite.php` | `50 * * * *` (hourly) | writes 856 ASN ship notices to `/out` |
+
+- **`/in`** — inbound orders Staples uploads for TOGA to import.
+- **`/out`** — outbound 855/856 files TOGA writes for Staples to download (drained by
+  Staples, moved to `/archive` on pickup).
+
+### Threshold tuning (decided)
+
+- Aged-file cutoff: **120 min for `/in`** (tied to the hourly import) and **240 min for
+  `/out`**.
+- Alarm when **>= 6 aged files** (tunable — can drop to 1 for single-file sensitivity).
+- **5-minute cron cadence** (`*/5 * * * *`), chosen to pair with the OneUptime heartbeat
+  criteria (received-in-8-min + `alarm:OK` recovery; not-received-15-min offline;
+  not-received-10-min degraded), matching the existing Compass monitor convention rather
+  than the source crons' hourly rate. The fast cadence is for a **reliable heartbeat**, not
+  because the folders change that fast — the folder cutoffs above are calibrated against the
+  **hourly 1.0 crons**, per the shared doc's "calibrate against the tier that runs the
+  business logic" rule.
+
+## Gotchas / known issues
+
+- **phpseclib3 `rawlist` returns arrays, and its SFTP type constants are not loaded** — see
+  the shared doc's
+  [SFTP monitoring gotchas](../../../2.0/apps/worker2/features/oneuptime-worker2-monitoring.md#sftp-monitoring-phpseclib3).
+  Getting this wrong silently makes the aged-file count always 0, so the monitor never
+  alarms and looks healthy.
+- The `[sftp_staples]` password and the OneUptime push URLs are credentials — reference
+  their location, never their value.
+
+## Change history
+- 2026-08-20 — Built the two SFTP folder monitors (`Monitor/Staples/InboundOrderQueue` on
+  `/in`, `Monitor/Staples/OutboundPickupQueue` on `/out`), each also acting as an SFTP
+  connectivity check via `status:error`; added the `[sftp_staples]` config group and the
+  `2026-08-20a` cron-registration migration; set the `/in` 120-min / `/out` 240-min aged-file
+  cutoffs and the >=6-file alarm threshold; chose a 5-min cadence for the heartbeat.
+  Motivated by the earlier `/out` pickup pileup incident that had no alerting. (bala)
+
+## Related docs
+- [OneUptime push-metric monitors for 2.0 workers](../../../2.0/apps/worker2/features/oneuptime-worker2-monitoring.md) — the shared pattern, payload contract, and runbook.
+- [Staples profile](../profile.md)
+- [Staples cXML order import (1.0)](../../../1.0/apps/worker/features/staples-cxml-order-import.md) — the inbound pipeline these monitors watch.
+</content>
+</invoke>

package/knowledge/clients/staples/profile.md

@@ -3,17 +3,20 @@ title: Staples
 framework: "1.0"
 apps:
   - worker
+  - worker2
+  - dbchanges2
 project: Worker
 client: staples
 type: profile
 status: active
-updated: 2026-08-13
-owners: [jcardinal]
+updated: 2026-08-20
+owners: [jcardinal, bala]
 files:
   - worker/crons/sync/staples/sync_staples_cxml.php
   - worker/crons/sync/staples/staples_asn_netsuite.php
 related:
   - ../../1.0/apps/worker/features/staples-cxml-order-import.md
+  - ./features/oneuptime-sftp-folder-monitors.md
 ---
 
 ## Summary

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toga-ai",
-  "version": "1.0.626",
+  "version": "1.0.628",
   "description": "TOGA Technology Team Claude Knowledge System — shared AI coding harness with skills, knowledge base CLI, and project installer for Claude Code.",
   "keywords": [
     "claude",