toga-ai 1.0.571 → 1.0.573

package/knowledge/1.0/apps/worker/INDEX.md

@@ -11,6 +11,7 @@
 | [OneUptime Server monitor + disk/memory hygiene on the 1.0 worker EB host](features/oneuptime-server-monitor-host-hygiene.md) | The 1.0 `agilant-worker` EB environment runs on the **legacy Amazon Linux 1 PHP 7.2 platform** (Apache httpd/prefork, s3fs mounts, cron) and repeatedly went dow | worker/.ebextensions/040_disk_memory_hygiene.config, worker/.ebextensions/045_oneuptime_agent.config, worker/ebs/cron.worker.php, worker/ebs/mount-s3fs-folders.php, worker/ebs/apache_settings.php, worker/ebs/setup_phpini.php |
 | [OneUptime external uptime monitoring for 1.0 workers](features/oneuptime-worker-uptime-monitoring.md) | Every 1.0 worker box self-reports its liveness to an external OneUptime monitor once per minute by curl-POSTing to a per-worker "Incoming Request" heartbeat URL | library/app/worker.php, worker/crons/worker/worker_heartbeat.php |
 | [Prudential: Send Shipments for the Day report (daily cron)](features/send-shipments-for-the-day.md) | Daily cron (9:00 PM) that emails Prudential and Dell stakeholders an Excel report of all devices shipped that day, including tracking number, serial number, emp | worker/crons/notifications/reports/send_shipments_for_the_day.php |
+| [Staples cXML Order Import (SFTP → NetSuite)](features/staples-cxml-order-import.md) | `sync_staples_cxml.php` is an **hourly** cron (runs at **:45**) that imports Staples cXML purchase orders from SFTP into NetSuite as Sales Orders, then writes a | worker/crons/sync/staples/sync_staples_cxml.php |
 | [Diagnosing frozen 1.0 worker cron check-ins (Sentry "missed" flood)](workflows/diagnosing-frozen-cron-checkins.md) | When 1.0 worker cron timestamps freeze and Sentry project `worker1` fills with **`missed`** check-ins, the intuitive diagnosis — a wedged `App_Framework::isProc | worker/.ebextensions/cron.config, library/app/worker.php |
 | [isFulfillable Multi-Client Backfill (all togasupply clients)](workflows/isfulfillable-multi-client-backfill.md) | One-time backfill that catches up `Items.isFulfillable` on **existing** items across **all 17 togasupply clients** (AIG, Broward Sheriff, Canon, Endeavor Health | worker/crons/toga2/netsuite/backfill_isfulfillable_all_clients.php, library/app/api/toga2.php |
 | [Onboarding a Client to the NetSuite TOGa Supply Sync](workflows/onboarding-client-to-netsuite-togasupply-sync.md) | How to add a new TOGa 2 client to the per-client NetSuite → TOGa Supply importer (`worker/crons/toga2/netsuite/`). | worker/crons/toga2/netsuite/sync_togasupply.php, worker/crons/toga2/netsuite/common_sync_togasupply.php, worker/crons/toga2/netsuite/sync_togasupply_elite.php, worker/schedules/cron.worker.sync.json, dbchanges2/_modules/netsuite/2026-04-01 - Parameters.sql, dbchanges2/_modules/netsuite/2026-08-05 - CLEAN NETSUITE CLINET.SQL |

package/knowledge/1.0/apps/worker/features/staples-cxml-order-import.md

@@ -0,0 +1,96 @@
+---
+title: Staples cXML Order Import (SFTP → NetSuite)
+framework: "1.0"
+repo: worker
+project: Worker
+client: staples
+type: client-feature
+status: active
+updated: 2026-08-13
+owners: [jcardinal]
+files:
+  - worker/crons/sync/staples/sync_staples_cxml.php
+related:
+  - clients/staples/profile.md
+---
+
+## Summary
+
+`sync_staples_cxml.php` is an **hourly** cron (runs at **:45**) that imports Staples cXML
+purchase orders from SFTP into NetSuite as Sales Orders, then writes an 855 acknowledgement
+back. Staples is NetSuite parent entity/customer **internalId 30057**.
+
+Flow per run: log into SFTP `sftp.goagilant.com` as `staplessftp`, list `/in`, and for each
+cXML order file:
+
+1. Replace a known part-number escaping edge case in the raw file.
+2. Parse via `App_Xml`.
+3. Log the raw file to **FileLog** (schema `Logs`, table `FileLog`, job
+   `STAPLES_IMPORT_ORDER`). `App_Model_Logs_FileLog` sets
+   `_databaseNameOverride = 'Logs'`, so this writes to the legacy/V1 prod schema `Logs`.
+   The full inbound cXML is stored in `FileLog.fileData`.
+4. Dedupe against existing NetSuite sales orders by customer PO
+   (`App_NetSuite::getSalesOrdersByCustomerPo`).
+5. Build and add a NetSuite `SalesOrder` under parent customer internalId 30057.
+6. On successful add: write an **855 acknowledgement** cXML to SFTP `/out`, archive the
+   source file to `/archive/archive_in`, and delete it from `/in`.
+
+### Line-item Location resolution
+
+Each line-item's **Location** is resolved by matching the order's Staples `CustomerID`
+(from `<Extrinsic name="CustomerID">`) against NetSuite **saved search 8412**:
+
+- match key: `custentity_external_customer_id`
+- location value: `custentity_customer_location`
+
+If no match is found, `$internalClientLocationId` stays **NULL**, the line-item Location is
+empty, and **NetSuite rejects the whole add** with `USER_ERROR` "Please enter value(s) for:
+Location".
+
+## Onboarding rule — new Staples buying account
+
+A Staples buying account is a **NetSuite child customer** of parent 30057. Before that
+account's first order arrives it must exist in NetSuite with:
+
+- **External Customer ID** = the account's Staples `CustomerID`, and
+- a valid **Customer Location**
+
+so it appears in saved search 8412. If it is missing (or has no Customer Location), every
+order for that account fails the NetSuite add and the file sits on SFTP `/in` retrying
+hourly forever — **with no error surfaced** (see gotchas). Coordinate with the NetSuite
+business admins to create the customer before go-live for any new account.
+
+## Gotchas / known issues
+
+**Silent-swallow of failed NetSuite adds (durable warning).** The
+`if ($response->writeResponse->status->isSuccess)` block (~line 888) has **no `else`**. A
+failed add logs nothing, emails no one, and leaves the file on `/in`. A file only leaves
+`/in` on (a) add success — ack + archive + delete — or (b) the "already processed" dedupe
+branch — delete. A failed add never removes it, so a pure data gap (e.g. an un-set-up
+customer) is invisible and retries indefinitely. This is why a real backlog went unnoticed
+for ~6 days.
+
+**`getSavedSearch(8412)` is called once per order inside the file loop** — expensive
+(~20s/file). A future refactor should fetch/cache it once per run.
+
+**Recommended hardening (NOT yet implemented):**
+- Add the missing `else` to email + log add failures (mirror the existing "missing items"
+  email) and leave the file for retry.
+- Pre-guard: if `$internalClientLocationId` is NULL, skip the doomed add and alert
+  "Staples customer `<CustomerID>` not set up in NetSuite", naming the exact id.
+
+## Diagnostic technique — early PHP-warning exit vs. silent add-failure
+
+In Worker 1.0 a PHP warning/notice **hard-exits** the cron (`App_Error` → `exit`), so
+nothing after the failure point runs. This cron writes its **FileLog** row (job
+`STAPLES_IMPORT_ORDER`) **before** any NetSuite call. So counting fresh FileLog rows for a
+run distinguishes the two failure modes:
+
+- **few** rows → it died early (a PHP warning aborted the run partway), vs.
+- **one row per file** → it processed every file but the NetSuite adds failed.
+
+Because the full inbound cXML lives in `FileLog.fileData`, ship-to identity and `CustomerID`
+can be recovered directly from the legacy `Logs` DB without touching SFTP.
+
+## Change history
+- 2026-08-13 — Documented feature (first KB entry). Diagnosed a ~6-day, ~30-order backlog stuck on SFTP `/in`: NetSuite rejected every add with `USER_ERROR` "Location" because new child customer INTEGRA PARTNERS INC. (Staples CustomerID 03716185, under parent 30057) was not set up in NetSuite → no saved-search-8412 match → NULL line-item Location. 28 of 30 stuck files were this account; 2 were CustomerID 05611619 (existed but missing Customer Location). Fixed by business admins creating the customer with External Customer ID + Customer Location; re-running the cron drained the backlog. Confirmed working. (jcardinal)

package/knowledge/2.0/apps/api2/features/record-scripts.md

@@ -6,8 +6,8 @@ project: API
 client: shared
 type: feature
 status: active
-updated: 2026-08-04
-owners: ["kyalamarthi", "mhammontree"]
+updated: 2026-08-13
+owners: ["kyalamarthi", "mhammontree", "tcox"]
 files:
   - api2/Component/Api/V2/V2.php
   - _underscore/Model/Team/Sprint.php
@@ -19,6 +19,7 @@ related:
   - ./tableview-apiwhereclause-row-filtering.md
   - ../architecture.md
   - ../../_underscore/features/per-client-database-connections.md
+  - ../../../../standalone/apps/togatech/features/careers-paylocity-job-openings.md
   - ../../worker2/features/team-sprint-management.md
 ---
 
@@ -233,8 +234,14 @@ CLIENT database as a `CustomRecordScript` — NOT in `Core.RecordScripts`.** Fir
   (Addresses 13, Sales orders 14, Entitlements 191, Subscriptions 253). This is safe;
   `Core.RecordScripts` ids are **not** (they have drifted per environment).
 - **Grant `Base` only, resolved by NAME** — role ids differ per client.
-- **Do NOT grant `Public`.** A warranty-availability endpoint reveals whether a warranty exists
-  at an arbitrary address; unauthenticated probing must be prevented.
+- **Do NOT grant `Public`** *unless the payload is genuinely public information.* A
+  warranty-availability endpoint reveals whether a warranty exists at an arbitrary address, so
+  unauthenticated probing must be prevented. The legitimate opposite case is
+  `GET /v2/campaigns/jobs` (`_Model_True_Campaign::jobs`), which proxies TOGA's public Paylocity
+  recruiting feed for the marketing site and **is** granted to True role 4 (Public) — see
+  [Careers — Paylocity job openings](../../../../standalone/apps/togatech/features/careers-paylocity-job-openings.md).
+  The test is "would an anonymous caller learn anything they shouldn't?", not "is Public ever
+  allowed?".
 - Verified by applying the file **twice** to two environments: exactly one script row and one
   grant row each.
 
@@ -302,6 +309,16 @@ an `AclRecordScripts` grant in each client DB.
   prior value and restore it, or you disable caching for the rest of the request.
 - **`aclDatabase` has no `TEAM`.** A `Team`-schema record registers as `'CORE'`; picking
   `'CLIENT'` sends the engine looking in the wrong cluster.
+- **⚠ Never hardcode a `Core.RecordScripts` id in a grant — it WILL be renumbered on apply.**
+  Concrete case (verified on production 2026-08-13): `Core/2026-07-15a -
+  CampaignPaylocityJobsRecordScript.sql` wrote the `campaigns`/`jobs` script as **id 25** ("next
+  free; prod max was 24"), and its sibling `Client_True/2026-07-16a -
+  CampaignPaylocityJobsScriptAcl.sql` granted `recordScriptId = 25` — but the row landed as **id
+  30** in production, so the grants pointed at nothing and a later file
+  (`Client_True/2026-08-05 - CampaignsJobsPublicAcl.sql`) had to re-grant against 30. A grant that
+  references a stale id inserts a row happily and fails **only** at request time as a missing-grant
+  error. Resolve the id by `recordId` + `method` + `route` where the databases allow it, and always
+  verify the actual id in the target environment.
 - **Registration is per-environment and split.** A missing `Core.RecordScripts` row → the route
   isn't a script (falls through to normal CRUD / 404-shaped behavior); a missing
   `AclRecordScripts` grant → the caller's roles can't run it. Both rows must exist in every
@@ -315,6 +332,11 @@ an `AclRecordScripts` grant in each client DB.
 
 ## Change history
 
+- 2026-08-13 — TRUE-80091/TRUE-80094 (`GET /v2/campaigns/jobs`): added the concrete evidence that a
+  **hardcoded `Core.RecordScripts` id in an ACL grant gets renumbered on apply** (written as 25,
+  landed as 30 in production, so the first grant file pointed at nothing and a second file had to
+  re-grant), and softened "never grant Public" to "not unless the payload is genuinely public" —
+  the jobs feed proxy is a legitimate Public grant. (tcox)
 - 2026-08-06 — TRUE-80282 testing: sharpened the envelope contract from ambiguous ("nested under the
   route segment") to the explicit **two-level `data.<recordRoute>.<scriptRoute>`**, with a
   route-vs-`phpMethod` table and the working precedent

package/knowledge/2.0/apps/toga-blox/features/api-client.md

@@ -6,8 +6,8 @@ project: TOGa Blox
 client: shared
 type: feature
 status: active
-updated: 2026-06-23
-owners: [apeterson]
+updated: 2026-08-13
+owners: [apeterson, tcox]
 files:
   - toga-blox/src/api/index.ts
   - toga-blox/src/api/axiosInstance.ts
@@ -95,6 +95,20 @@ Filterable`, `hyperlinkField`, `imageUrlField`, `sticky`, `precision`, …), `Da
 - Only **401** auto-retries; other network errors need React Query `retry`.
 - 401 refresh needs a `refreshToken` in localStorage, else it logs out (hard redirect to `/`).
 - `transactionId` is injected automatically (request tracing); `depth=-1` returns hydrated nesting.
+- **⚠ `fetchPublicToken()` (`POST /auth/public`) is ORIGIN-GATED** — api2 resolves the browser's
+  `Origin` header against `Core.Domains` to establish `appId`/`clientId` before minting, and
+  rejects an unregistered origin with **EN-6 "domain not permitted"**. Every **host variant needs
+  its own `Core.Domains` row**: verified 2026-08-13 that `https://togatech.com` and
+  `http://localhost` (any port — the port is stripped) are allowed while
+  **`https://www.togatech.com` is rejected**. Symptom on a public marketing page is *silent* —
+  no token, so every anonymous fetch fails and the section renders its empty state. Fix is a
+  `Core.Domains` row, not frontend code. See
+  [encrypted user-uuid auth handoff](../../api2/features/encrypted-user-uuid-auth-handoff.md) for
+  the same gating on the SSO handoff route.
 
 ## Change history
+- 2026-08-13 — TRUE-80091: recorded that `fetchPublicToken()`/`POST /auth/public` is **origin-gated
+  against `Core.Domains` (EN-6 on an unregistered origin)** and that each host variant needs its own
+  row — `www.togatech.com` is rejected while `togatech.com` and `localhost` are allowed, which
+  silently blanks anonymous data on a public site. (tcox)
 - 2026-06-23 — Documented the API client: axios init contract, auth/refresh interceptors, query-option serialization, generic CRUD, table-data fetchers, and the 2.0 response envelope (apeterson).

package/knowledge/INDEX.md

@@ -5,7 +5,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 ## 1.0 framework
 
 - **library** (Library) _(framework core)_ — 18 doc(s) → [1.0/apps/library/INDEX.md](1.0/apps/library/INDEX.md)
-- **worker** (Worker) — 23 doc(s) → [1.0/apps/worker/INDEX.md](1.0/apps/worker/INDEX.md)
+- **worker** (Worker) — 24 doc(s) → [1.0/apps/worker/INDEX.md](1.0/apps/worker/INDEX.md)
 - **dbchanges** (Database Changes) _(framework core)_ — 1 doc(s) → [1.0/apps/dbchanges/INDEX.md](1.0/apps/dbchanges/INDEX.md)
 - **worker1.5** (Worker 1.5) — 0 doc(s) → [1.0/apps/worker1.5/INDEX.md](1.0/apps/worker1.5/INDEX.md)
 - **togadesk** (TOGa Desk) — 12 doc(s) → [1.0/apps/togadesk/INDEX.md](1.0/apps/togadesk/INDEX.md)
@@ -36,7 +36,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 
 ## standalone framework
 
-- **togatech** (TOGA Technology Website) — 4 doc(s) → [standalone/apps/togatech/INDEX.md](standalone/apps/togatech/INDEX.md)
+- **togatech** (TOGA Technology Website) — 6 doc(s) → [standalone/apps/togatech/INDEX.md](standalone/apps/togatech/INDEX.md)
 - **websocket** (WebSocket Server) — 2 doc(s) → [standalone/apps/websocket/INDEX.md](standalone/apps/websocket/INDEX.md)
 - **forward** (Forwarder) — 3 doc(s) → [standalone/apps/forward/INDEX.md](standalone/apps/forward/INDEX.md)
 - **claude** (Claude Harness) — 7 doc(s) → [standalone/apps/claude/INDEX.md](standalone/apps/claude/INDEX.md)
@@ -57,6 +57,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 - **Quad Graphics** (`quad`) → [clients/quad/INDEX.md](clients/quad/INDEX.md)
 - **Rate** (`rate`) → [clients/rate/INDEX.md](clients/rate/INDEX.md)
 - **Richmond University Medical Center** (`rumcsi`) → [clients/rumcsi/INDEX.md](clients/rumcsi/INDEX.md)
+- **Staples** (`staples`) → [clients/staples/INDEX.md](clients/staples/INDEX.md)
 - **Tow Foundation** (`tow-foundation`) → [clients/tow-foundation/INDEX.md](clients/tow-foundation/INDEX.md)
 - **TOGA Technology** (`true`) → [clients/true/INDEX.md](clients/true/INDEX.md)
 - **Walmart Client Profile** (`walmart`) → [clients/walmart/INDEX.md](clients/walmart/INDEX.md)

package/knowledge/clients/staples/INDEX.md

@@ -0,0 +1,5 @@
+# Client: Staples `staples`
+
+| Doc | Framework | Summary | Files |
+|-----|-----------|---------|-------|
+| [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/profile.md

@@ -0,0 +1,41 @@
+---
+title: Staples
+framework: "1.0"
+apps:
+  - worker
+project: Worker
+client: staples
+type: profile
+status: active
+updated: 2026-08-13
+owners: [jcardinal]
+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
+---
+
+## Summary
+
+Staples is a **headless** integration client — no UI, Worker 1.0 only, depending on the
+`library` (1.0 `App_`) core. Its entire footprint is two crons under
+`worker/crons/sync/staples/`:
+
+1. **`sync_staples_cxml.php`** — hourly inbound: pulls cXML purchase orders off SFTP,
+   creates NetSuite Sales Orders, and writes 855 acknowledgements back. This is the
+   documented feature — see
+   **`1.0/apps/worker/features/staples-cxml-order-import.md`**.
+2. **`staples_asn_netsuite.php`** — outbound ASN (Advance Ship Notice) from NetSuite back
+   to Staples. (Not yet documented in detail.)
+
+**NetSuite identity:** Staples is the NetSuite parent entity/customer **internalId 30057**.
+Individual Staples buying accounts are NetSuite **child customers** matched by their Staples
+`CustomerID` against **saved search 8412** (match key `custentity_external_customer_id`;
+location from `custentity_customer_location`).
+
+**Onboarding rule (load-bearing):** any new Staples buying account must be set up in
+NetSuite — as a child customer of 30057, with its **External Customer ID** = the Staples
+`CustomerID` **and** a valid **Customer Location** — *before* its first order arrives.
+Miss either and inbound orders for that account silently jam on SFTP with no error (see the
+feature doc's gotchas).

package/knowledge/clients/true/profile.md

@@ -7,12 +7,13 @@ apps:
   - worker2
   - dbchanges2
   - api2
+  - togatech
 project: _Underscore
 client: true
 type: profile
 status: active
-updated: 2026-08-04
-owners: [jcardinal, kyalamarthi]
+updated: 2026-08-13
+owners: [jcardinal, kyalamarthi, tcox]
 files: []
 related:
   - clients/true/features/users-personas-data-model.md
@@ -34,6 +35,14 @@ Scripts on `_Model_Team_Sprint` (over the `Team` schema), with the `AclRecordScr
 scoped to True roles 1/3/4 — hence `api2` is in this client's `apps`. See
 [Sprint Dashboard API](../../2.0/apps/api2/features/sprint-dashboard-api.md).
 
+The public **TOGA Technology website** (repo `togatech`, standalone React SPA, app id **41**
+"TOGa Technologies Website") is True's own marketing site and consumes True-scoped api2 endpoints
+**anonymously**: the toga-blox client mints a public token from `POST /v2/auth/public` (gated on
+`Origin` against `Core.Domains` — `togatech.com` is registered, `www.togatech.com` is **not**) and
+calls `GET /v2/campaigns/jobs`, a Record Script on `_Model_True_Campaign` granted to True roles 1
+(Base) and 4 (Public). See
+[Careers — Paylocity job openings](../../standalone/apps/togatech/features/careers-paylocity-job-openings.md).
+
 The **Tools** app (1.0; repo `tools`) authenticates True users via **SSO** through
 `saml.togahub.com` and reads the `Client_True` DB **read-only** to gate its internal tooling by
 staff persona (see `1.0/apps/tools/`). Its gateway return domain is registered in `Core.Domains`

package/knowledge/standalone/apps/togatech/INDEX.md

@@ -3,5 +3,7 @@
 | Doc | Summary | Files |
 |-----|---------|-------|
 | [TOGA Technology Website Architecture](architecture.md) | The public-facing TOGA Technology corporate/marketing website. | togatech/src/main.tsx, togatech/src/App.tsx, togatech/src/routes.tsx, togatech/src/lib/api.ts, togatech/src/lib/contentful.ts, togatech/src/themeConfig/ThemeContext.tsx, togatech/vite.config.ts, togatech/package.json |
+| [Careers Section — Live Paylocity Job Openings (About page + /v2/campaigns/jobs proxy)](features/careers-paylocity-job-openings.md) | The togatech **About** page renders a "Join Our Team" careers section listing **live job openings pulled from TOGA's Paylocity recruiting feed**. | togatech/src/pages/About/AboutPage.tsx, togatech/src/pages/About/types.ts, togatech/src/pages/About/view/components/JobOpening/JobOpening.tsx, togatech/src/pages/About/viewModel/useAboutViewModel.ts, togatech/src/pages/About/viewModel/FIELDS/ABOUTPAGEFIELDS.json, togatech/cypress/e2e/aboutPage/jobPosting.cy.ts, _underscore/Model/True/Campaign.php, dbchanges2/Core/2026-07-15a - CampaignPaylocityJobsRecordScript.sql, dbchanges2/Client_True/2026-07-16a - CampaignPaylocityJobsScriptAcl.sql, dbchanges2/Client_True/2026-08-05 - CampaignsJobsPublicAcl.sql |
 | [SEO / AEO / GEO — Prerendering, Single-Source Meta & Structured Data](features/seo-aeo-geo-prerender.md) | Makes togatech.com visible and citable to search engines **and** AI answer engines (ChatGPT/Perplexity/Claude search, Google AI Overviews). | togatech/vite.config.ts, togatech/scripts/prerender.mjs, togatech/src/routes.config.json, togatech/src/main.tsx, togatech/src/App.tsx, togatech/src/components/SEO/Seo.tsx, togatech/src/components/SEO/JsonLd.tsx, togatech/src/components/SEO/schema.ts, togatech/src/components/templates/AppLayout.tsx, togatech/src/pages/WhatWeDo/WhatWeDoPage.tsx, togatech/src/pages/WhatWeDo/viewModel/FIELDS/WHATWEDOPAGEFIELDS.json, togatech/src/pages/About/AboutPage.tsx, togatech/src/pages/Contact/ContactPage.tsx, togatech/src/pages/OurPlatform/OurPlatformPage.tsx, togatech/public/robots.prod.txt, togatech/public/sitemap.xml, togatech/public/llms.txt |
 | [Creating Pull Requests on togatech](workflows/creating-pull-requests.md) | How to open a PR against `agilantsolutions/togatech`. | togatech/.git/config |
+| [Running togatech Locally & Verifying a Page Without Cypress](workflows/local-dev-and-headless-verification.md) | The gotcha-avoidance path for getting `togatech` up on a dev machine and actually *seeing* a data-driven section render. | togatech/package.json, togatech/cypress.config.ts, togatech/src/App.tsx |

package/knowledge/standalone/apps/togatech/features/careers-paylocity-job-openings.md

@@ -0,0 +1,157 @@
+---
+title: Careers Section — Live Paylocity Job Openings (About page + /v2/campaigns/jobs proxy)
+framework: "standalone"
+repo: togatech
+project: TOGA Technology Website
+client: shared
+type: feature
+status: active
+updated: 2026-08-13
+owners: ["tcox"]
+files:
+  - togatech/src/pages/About/AboutPage.tsx
+  - togatech/src/pages/About/types.ts
+  - togatech/src/pages/About/view/components/JobOpening/JobOpening.tsx
+  - togatech/src/pages/About/viewModel/useAboutViewModel.ts
+  - togatech/src/pages/About/viewModel/FIELDS/ABOUTPAGEFIELDS.json
+  - togatech/cypress/e2e/aboutPage/jobPosting.cy.ts
+  - _underscore/Model/True/Campaign.php
+  - dbchanges2/Core/2026-07-15a - CampaignPaylocityJobsRecordScript.sql
+  - dbchanges2/Client_True/2026-07-16a - CampaignPaylocityJobsScriptAcl.sql
+  - dbchanges2/Client_True/2026-08-05 - CampaignsJobsPublicAcl.sql
+related:
+  - ../architecture.md
+  - ../../../../2.0/apps/api2/features/record-scripts.md
+  - ../../../../2.0/apps/toga-blox/features/api-client.md
+---
+
+# Careers Section — Live Paylocity Job Openings
+
+## Summary
+
+The togatech **About** page renders a "Join Our Team" careers section listing **live job
+openings pulled from TOGA's Paylocity recruiting feed**. The browser never touches Paylocity:
+the site calls **`GET /v2/campaigns/jobs`** on api2, which dispatches a **Record Script** to
+`_Model_True_Campaign::jobs()` in `_underscore`, which server-side proxies the public Paylocity
+feed. The endpoint is reachable **unauthenticated** (public role) via the anonymous token that
+toga-blox mints from `POST /v2/auth/public`.
+
+Backend (TRUE-80094: model method + api2 registration + ACL migrations) is **merged and live in
+production** — verified 2026-08-13 returning 7 real postings. The frontend move (TRUE-80091) puts
+the section on **About**; it previously lived on the **Contact** page against static/Contentful
+content, and that Contact-page jobs code, types, fields, and Cypress spec were removed.
+
+## Key files / entry points
+
+**Frontend (togatech):**
+- `src/pages/About/viewModel/useAboutViewModel.ts` — React Query fetch (`queryKey: ['jobPosts']`,
+  24h `staleTime`), envelope unwrap, and `mapJobs()` (Paylocity shape → view shape).
+- `src/pages/About/view/components/JobOpening/JobOpening.tsx` — presentational section (moved
+  from `pages/Contact/`); testids `job-posting-section` / `job-opening-cards`.
+- `src/pages/About/AboutPage.tsx` — renders `<JobOpening>` between **Culture** and the
+  **Carousel**.
+- `src/pages/About/viewModel/FIELDS/ABOUTPAGEFIELDS.json` — new **`careers`** block (heading,
+  subheading, "View All Openings" LinkedIn button, image + alt text).
+- `src/pages/About/types.ts` — `JobOpening`, `JobPostFields`.
+- `cypress/e2e/aboutPage/jobPosting.cy.ts` — moved from `cypress/e2e/contactPage/`, now visits
+  `/about`.
+
+**Backend:**
+- `_underscore/Model/True/Campaign.php` — `public static function jobs(&$api): object` plus the
+  `PAYLOCITY_JOBS_FEED_URL` const (public per-company recruiting feed URL; no credential) and
+  `HTTP_STATUS_SUCCESS_MIN/MAX`.
+- api2 dispatch: `Core.RecordScripts` row for record `campaigns` (**recordId 296**), `method GET`,
+  `route jobs`, `phpMethod jobs`.
+
+## How it works
+
+1. **Fetch.** `useAboutViewModel` calls toga-blox `apiGet('campaigns/jobs')` against base
+   `VITE_API` (`https://api.togahub.com/v2` in production).
+2. **Auth.** The toga-blox axios interceptor finds no `accessToken` in localStorage and mints an
+   anonymous one with `POST /v2/auth/public` (no body), then sends it as `Authorization: Bearer`.
+3. **Dispatch.** api2's `/v2` engine matches `campaigns` (record 296) + trailing segment `jobs`
+   to the `Core.RecordScripts` row and invokes `_Model_True_Campaign::jobs(&$api)`. Authorization
+   comes from the **script grant**, not record CRUD ACL — see
+   [Record Scripts](../../../../2.0/apps/api2/features/record-scripts.md).
+4. **Server-side proxy.** `jobs()` issues a `GET` through `_ApiRequest` (`ENCODE__JSON`) to
+   `PAYLOCITY_JOBS_FEED_URL` with `setThrowExceptionsOnFailure(false)`, and returns
+   `{success: true, jobs: <decoded feed>}`. On a thrown exception, a non-2xx `responseCode`, or a
+   null body it `error_log`s and returns `{success: false, error: '<message>'}` — **the HTTP call
+   still succeeds with envelope `isSuccess: true`**, so `data…success` is the inner proxy status
+   and is distinct from the platform envelope flag. **Why proxy:** keeps the feed's CORS/origin
+   concerns server-side and gives the frontend one consistent API shape.
+5. **Unwrap + map.** The view model reads `envelope.data.campaigns.jobs.jobs.jobs ?? []` (see the
+   gotcha below), then `mapJobs()` projects each entry to
+   `{id, title, location, type, compensation, postLink}`:
+   `jobId → id`, `jobLocation.locationDisplayName → location`,
+   `jobTypesArray[0] ?? jobTypes → type`, `salaryDescription → compensation`,
+   `applyUrl ?? displayUrl → postLink`.
+6. **Render.** Each card shows title, a target-blank **Apply** link, and a dot-separated
+   location / type / compensation row. Empty array → **"No job openings available at this
+   time."** (the section itself always renders; copy and image come from the `careers` FIELDS
+   block, so a feed outage degrades to static content).
+
+## Data model
+
+No local schema. The Paylocity feed entries carry `jobId`, `title`, `salaryDescription`,
+`applyUrl`, `displayUrl`, `jobTypes`, `jobTypesArray[]`, `jobLocation.locationDisplayName`.
+
+Registration/ACL metadata (all merged to dbchanges2 `_main` and applied to production):
+
+| Migration | What it does |
+|---|---|
+| `Core/2026-07-15a - CampaignPaylocityJobsRecordScript.sql` | `Core.RecordScripts` row: recordId **296** (`campaigns`), `GET`, route `jobs`, phpMethod `jobs`. Written with **id 25** (next free at the time). |
+| `Client_True/2026-07-16a - CampaignPaylocityJobsScriptAcl.sql` | `AclRecordScripts` grants to True roles **1 (Base)** and **4 (Public)** — `campaigns` is a CLIENT-`aclDatabase` record, so the caller's *client* roles are checked. |
+| `Client_True/2026-08-05 - CampaignsJobsPublicAcl.sql` | Adds the record-level READ grant for role 4 per app (`AclRecordPermissions`, appId **41** "TOGa Technologies Website" and **39** Talos) **plus** an `AclRecordScripts` invoke grant referencing script id **30**. |
+
+## Client variations
+
+None. The feed is TOGA's own (client **True** / `Client_True`); no other tenant consumes it.
+
+## Gotchas / known issues
+
+- **⚠ The array is nested FOUR levels: `data.campaigns.jobs.jobs.jobs`.** Two levels come from
+  the record-script envelope contract (`data.<recordRoute>.<scriptRoute>` = `data.campaigns.jobs`),
+  the third from the method's own `{success, jobs}` wrapper, and the fourth because the Paylocity
+  feed object *itself* has a `jobs` key. Reading one level short yields `undefined` → an
+  empty-looking careers section with no error.
+- **⚠ `POST /v2/auth/public` is DOMAIN-GATED on the `Origin` header** against `Core.Domains`.
+  Verified 2026-08-13: `https://togatech.com` ✅ and `http://localhost` (any port — the port is
+  stripped) ✅, but **`https://www.togatech.com` is REJECTED** with **EN-6 "domain not
+  permitted"**. If the site is ever served from the `www` host, no public token is minted and the
+  careers section silently renders "No job openings available at this time." Fix is a
+  `Core.Domains` row for the `www` origin, not a frontend change.
+- **The inner `success: false` is invisible to the envelope.** A Paylocity outage returns
+  HTTP 200 / `isSuccess: true` with `data.campaigns.jobs.success === false`; the frontend
+  currently ignores that flag and falls through to the empty state. Check `error_log`
+  (`Paylocity jobs feed request failed` / `returned HTTP <code>`) when jobs vanish in production.
+- **⚠ React Query is persisted to localStorage** (persister key `"commerce"`, 24h `staleTime`),
+  so after one successful load you will see **no network request** for `jobPosts` for a day.
+  When debugging, clear the persisted cache **and** `accessToken`/`refreshToken` from
+  localStorage — otherwise you are also testing a stale token.
+- **Script id drift.** The Core migration hardcodes RecordScript **id 25** while the later
+  Client_True ACL file references **id 30** — the row was renumbered when applied to production.
+  Trust the environment, not the file, when checking grants.
+- **Not shipped yet.** The frontend lives on branch **`TRUE-80091`** (committed, no PR at time of
+  writing); base branch for togatech PRs is **`_production`**, not `_main` (see
+  [Creating Pull Requests on togatech](../workflows/creating-pull-requests.md)).
+
+## Change history
+
+- 2026-08-13 — TRUE-80091: careers section moved to the **About** page (between Culture and
+  Carousel) and switched to the live Paylocity feed via `GET /v2/campaigns/jobs`; the old
+  Contact-page jobs code/types/fields and its Cypress spec were removed. Documented the
+  end-to-end path (TRUE-80094 backend, already live in production): api2 record-script dispatch →
+  `_Model_True_Campaign::jobs()` server-side proxy → four-level unwrap
+  `data.campaigns.jobs.jobs.jobs`, the public-role ACL/app grants, and the
+  **`www.togatech.com` `/auth/public` EN-6 rejection** that would blank the section. (tcox)
+
+## Related docs
+
+- [Record Scripts](../../../../2.0/apps/api2/features/record-scripts.md) — the authoring/dispatch
+  contract and the `data.<recordRoute>.<scriptRoute>` envelope rule.
+- [toga-blox API client](../../../../2.0/apps/toga-blox/features/api-client.md) — the axios
+  interceptor that mints and attaches the public token.
+- [togatech architecture](../architecture.md) — the SPA this section lives in.
+- [TOGA Technology client profile](../../../../clients/true/profile.md) — the tenant that owns the
+  endpoint.

package/knowledge/standalone/apps/togatech/workflows/local-dev-and-headless-verification.md

@@ -0,0 +1,75 @@
+---
+title: Running togatech Locally & Verifying a Page Without Cypress
+framework: "standalone"
+repo: togatech
+project: TOGA Technology Website
+client: shared
+type: workflow
+status: active
+updated: 2026-08-13
+owners: ["tcox"]
+files:
+  - togatech/package.json
+  - togatech/cypress.config.ts
+  - togatech/src/App.tsx
+related:
+  - ../architecture.md
+  - ../features/careers-paylocity-job-openings.md
+---
+
+# Running togatech Locally & Verifying a Page Without Cypress
+
+## Summary
+
+The gotcha-avoidance path for getting `togatech` up on a dev machine and actually *seeing* a
+data-driven section render. Three things bite in order: **stale `node_modules`** (the dev server
+fails outright), **`lint` cannot run from a clean install**, and **Cypress 15's binary fails its
+smoke test on Windows** — plus a persisted React Query cache that makes it look like nothing is
+fetching. Verified on Windows 11, 2026-08-13.
+
+## Steps
+
+1. **`npm install` before anything else, every time you pull.** A stale `node_modules` shows up as
+   a Vite resolve error, not as a missing dependency:
+   `"react-helmet-async" is imported by … but could not be resolved`. Both
+   `react-helmet-async` and `react-google-recaptcha-v3` are declared in `package.json` (added by
+   the SEO work) but absent from an older install, and the site simply will not load.
+2. **Start the dev server** — `npm run dev`, or `npm run togatech` for the `--host togatech` variant
+   (Vite `allowedHosts: ["togatech"]`).
+3. **Clear localStorage before judging any data fetch.** `App.tsx` wraps the app in
+   `PersistQueryClientProvider` with the persister key **`"commerce"`** and a **24h `staleTime`**,
+   so a previously cached query (e.g. `jobPosts`) renders from localStorage with **no network
+   request at all**. Clear the persisted cache **and** `accessToken` / `refreshToken` — a stale
+   public token from `POST /v2/auth/public` will otherwise be reused too.
+4. **Do not expect `npm run lint` to work.** The script is
+   `eslint . --ext ts,tsx --report-unused-disable-directives --max-warnings 0`, but **`eslint` is
+   not in `package.json` dependencies or devDependencies at all** — there is no local binary, so a
+   clean install cannot lint. Rely on `tsc` (`npm run build` = `tsc && vite build && …`) for type
+   safety and review manually, or install eslint ad hoc.
+5. **If Cypress won't run, verify headlessly with the repo's Puppeteer.** `cypress` 15.11 fails its
+   own binary verification on this Windows machine — `bad option: --smoke-test` — and
+   `npx cypress install` does **not** fix it. Workaround: `puppeteer` is already a dependency, so
+   drive **system Chrome** directly by passing `executablePath` to `puppeteer.launch()`, navigate to
+   the dev-server URL, and assert on the rendered DOM (the section testids, e.g.
+   `job-posting-section` / `job-opening-cards`). Same technique the production build already uses in
+   `scripts/prerender.mjs`.
+
+## Gotchas / known issues
+
+- A Vite "imported but could not be resolved" error almost always means **stale install**, not a
+  missing package — check `package.json` before adding a dependency.
+- `npm run lint` is effectively dead until eslint is added to the repo's dev dependencies; do not
+  treat a lint failure-to-start as a code problem.
+- Cypress specs are still the source of truth for e2e coverage — the Puppeteer route is a *local
+  verification* workaround, not a replacement. Don't delete or rewrite specs because Cypress won't
+  launch locally.
+- Watching the network tab is not proof a fetch is broken: see step 3 (persisted query cache).
+
+## Change history
+
+- 2026-08-13 — TRUE-80091: first recorded, from bringing the site up to verify the About-page
+  careers section — stale `node_modules` blocking the dev server (`react-helmet-async`,
+  `react-google-recaptcha-v3`), `eslint` missing from `package.json` so `npm run lint` can't run,
+  Cypress 15 `--smoke-test` binary failure on Windows with the Puppeteer + system-Chrome
+  workaround, and the localStorage-persisted React Query cache (key `"commerce"`, 24h staleTime)
+  masking fetches. (tcox)

package/package.json

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