toga-ai 1.0.1039 → 1.0.1041

package/knowledge/1.0/apps/worker/features/compass-partial-in-transit-delivered-emails.md

@@ -24,6 +24,7 @@ related:
   - ../../../clients/compass-usa/features/tracking-number-origin-and-asn-link.md
   - ../../../clients/compass-usa/features/contact-email-resolution.md
   - ../../../2.0/apps/worker2/features/tracking-status-refresh.md
+  - ../../../2.0/apps/worker2/features/all-client-email-queue-monitor.md
   - ../../../2.0/apps/worker2/features/oneuptime-worker2-monitoring.md
   - ../../../clients/compass-canada/features/french-order-email-localization.md
   - ../../../clients/compass-usa/features/order-fulfillment-status-per-line.md
@@ -375,9 +376,15 @@ the tracking number as emailed (it retries next run).
   as is (decided 2026-10-15, TRUE-82847).
 - Delivered template = prod `emailTemplateId` 26 in `Logs_Compass.Email`; baseline 2026-09-15..10-15:
   959 SENT, 1 FAILED.
+- **⚠ The delivered cron never checks the send result.** It calls `App_Api_Toga2::send(..., false)`
+  (`$throwExceptionOnApiError = false`) and ignores the response, so it marks
+  `TrackingNumbers.status = 'DELIVERED'` and inserts notifications even when api2 rejects the email.
+  Its "only mark DELIVERED after confirmed send" comment is wrong. "Sent" only means queued to
+  `Logs_Compass.Email`; worker2 `Infrastructure/Email/Send` does the real send. Not changed.
 
 ## Change history
 - 2026-10-15 — Delivered crons (USA + Canada) pick one active `Users` row with email + Contacts fallback; documented the 2-active-users duplicate. (jcardinal)
+- 2026-10-15 — Recorded that the delivered cron ignores the send result (TRUE-82846). (bala)
 - 2026-10-13 — Recorded that the USA delivered cron has no date window, so bulk ASN loads must suppress first. (bala)
 
 ## Related

package/knowledge/2.0/apps/worker2/features/all-client-email-queue-monitor.md

@@ -6,7 +6,7 @@ project: Worker
 client: shared
 type: feature
 status: active
-updated: 2026-09-16
+updated: 2026-10-15
 owners: ["jcardinal", "bala"]
 files:
   - worker2/Worker/Monitor/Operations.php
@@ -19,6 +19,7 @@ related:
   - ./monitoring-framework.md
   - ../../_underscore/features/email-send-pipeline.md
   - ../../_underscore/features/per-client-database-connections.md
+  - ../../../1.0/apps/worker/features/compass-partial-in-transit-delivered-emails.md
 ---
 
 Cross-client health check for the 2.0 outbound email queue (`Logs_<Client>.Email`); open when working on email-queue alerting or an all-client DB fan-out.
@@ -49,7 +50,9 @@ Steps:
 
 ### Alarm rule (explicit product decision)
 
-Alarm on **`FAILED > 0` only**. `PENDING` is reported as context and **never** alarms — a queue with work in it is normal, and the sender cron runs every minute.
+Alarm on **`FAILED > 0` only** (`ALARM_FAILED_COUNT = 0`). `PENDING` is reported as context and **never** alarms — a queue with work in it is normal, and the sender cron runs every minute.
+
+**No time window:** the count is every `FAILED` row ever, so **one** failed email holds the alarm `HIGH` until the 90-day `Email` cleanup removes it or someone changes its `status` by hand.
 
 ### Payload contract — `alarm` and `probe` are SEPARATE tokens
 
@@ -75,6 +78,7 @@ OneUptime can only string-match a request body (no numeric comparison, no JSON k
 
 ## Gotchas
 
+- **⚠ Triage: the OneUptime alarm "Compass email queue backlog is too high" IS this monitor** (the UI name was never renamed; there is no threshold of 20/25 and no `worker/monitor/compass/` code). It almost always means `FAILED` rows, not a backlog. First step: `SELECT id, subject, failureReason FROM Email WHERE status = 'FAILED'` on the named client's logs DB, then fix the **producer** that queued the bad row. 2026-10-15 (TRUE-82846): one row, `Logs_Compass.Email` id 146380, `failureReason` "You must provide at least one recipient email address.", 0 pending — caused by the Compass delivered cron, see [Compass in-transit & delivered emails](../../../1.0/apps/worker/features/compass-partial-in-transit-delivered-emails.md).
 - **⚠ This monitor is blind to an email that was never queued.** It reads `Logs_<Client>.Email`, so it can only see a send that already produced a row. If the producing cron dies, stalls or never selects the work, this monitor reports a **healthy empty queue**. That is exactly what happened during the Compass USA in-transit outage (2026-08-27 → 2026-09-03): the 1.0 sending cron timed out before creating a single email row and this monitor stayed green all week. Pair any email-queue monitor with a **backlog monitor on the producer's input** — first instance `Monitor/Compass/InTransitEmailQueue`, see [OneUptime push-metric monitors](./oneuptime-worker2-monitoring.md).
 - **A client's database name is NOT derivable from `clientIdentifier`.** `Compass_Usa` → `Logs_Compass`. Always resolve `Clients.logDatabaseId` → `Databases.name`. Building `'Logs_' . $clientIdentifier` silently targets a nonexistent database. See [per-client database connections](../../_underscore/features/per-client-database-connections.md).
 - **Do not use `_Database::registerClientDatabases()` for an all-client fan-out.** It INNER JOINs the client and archive databases alongside the log database, so a client missing either row drops out and the method then dereferences a null row and throws. It also opens three connections when only the log one is needed. Run a log-database-only variant with LEFT OUTER JOINs instead.
@@ -84,7 +88,10 @@ OneUptime can only string-match a request body (no numeric comparison, no JSON k
 - **An unconditional `SUM(status = 'X')` cannot use an index.** `SELECT SUM(status='FAILED') FROM Email` full-scans, reading every historical `SENT` row despite `idx_email_status`. Use `WHERE status IN (...) GROUP BY status`. This runs per client on a cron, so the difference compounds.
 - **There is no `_Query::setTimeout()` in the 2.0 framework** (only `_ApiRequest::setTimeout()`). A 2.0 worker therefore has **no per-query timeout**, so a hung database cluster blocks the fan-out until the connection itself times out. Relevant to any loop over all clients.
 - **A passing dev run does not prove cross-cluster correctness.** Non-prod is a single all-in-one database endpoint; production splits Core / `Client_*` / `Logs_*` / `Archive_*` / `Cache` across **separate clusters**.
-- **Verification status of this capture:** `php -l` passes; php-reviewer and sql-reviewer both returned 0 critical and every actionable finding was fixed. It has **not** been executed against any environment and **no database was queried** — the `Core` join shape is verified against framework source only, not against real rows.
+- **Live in prod** — it fired on a real Compass `FAILED` row on 2026-10-15.
+
+## Change history
+- 2026-10-15 — Recorded no-time-window alarm behavior and the "Compass email queue backlog" triage path; confirmed live in prod (TRUE-82846). (bala)
 
 ## Related
 

package/knowledge/INDEX.md

@@ -39,7 +39,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 
 ## standalone framework
 
-- **togatech** (TOGA Technology Website) — 8 doc(s) → [standalone/apps/togatech/INDEX.md](standalone/apps/togatech/INDEX.md)
+- **togatech** (TOGA Technology Website) — 10 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)
 - **talos** (TOGa Talos Chat) — 3 doc(s) → [standalone/apps/talos/INDEX.md](standalone/apps/talos/INDEX.md)
 - **talos-backend** (TOGa Talos) — 32 doc(s) → [standalone/apps/talos-backend/INDEX.md](standalone/apps/talos-backend/INDEX.md)

package/knowledge/clients/compass-canada/profile.md

@@ -144,6 +144,12 @@ to but distinct from Compass USA. Like Compass USA it spans the **2.0** commerce
   instead of **12 / 8 / 33**. Removing the hack gives them *more* access; whether Canada should get
   it is an **open decision**. See
   [Storefront persona gating](../../2.0/apps/toga2-commerce/features/storefront-persona-gating-and-home-counts.md).
+- **⚠ "Admin Canada" persona 31 grants only 2 categories (found 2026-10-15, TRUE-82848).** Categories
+  come from `Personas_Assortments`, not bundles/items. Persona 31 has every bundle + item but only
+  assortments 17 + 18, so a user with persona 31 alone (James Fuller, CA user 31583) sees 2 of 16
+  categories. Fix `dbchanges2/Client_CompassCanada/2026-10-15a - AdminCanadaPersonaAllAssortments.sql`
+  is **not yet run** in any env. See
+  [Copying a US user into Canada](workflows/copying-a-us-user-into-the-canada-tenant.md).
 - **⚠ "Blank page at `https://compasscanada.togacommerce.com/`" (reported by Compass Canada IT,
   Sept 2026) is a shared auth-gating bug, not a Canada or caching problem.** A stale **public**
   `accessToken` made the app think the visitor was signed in, so `/` rendered nothing until the

package/knowledge/clients/compass-canada/workflows/copying-a-us-user-into-the-canada-tenant.md

@@ -6,10 +6,11 @@ project: Database Changes
 client: compass-canada
 type: workflow
 status: active
-updated: 2026-09-28
+updated: 2026-10-15
 owners: [bala]
 files:
   - dbchanges2/Client_CompassCanada/2026-09-28a - AddJamesFullerSuperUser.sql
+  - dbchanges2/Client_CompassCanada/2026-10-15a - AdminCanadaPersonaAllAssortments.sql
   - worker2/Worker/Client/Compass/PeopleFile.php
 related:
   - ../profile.md
@@ -17,6 +18,7 @@ related:
   - ../../compass-usa/workflows/granting-persona-bundle-access.md
   - ../../../2.0/apps/dbchanges2/features/rerunnable-additive-inserts.md
   - ../../../2.0/apps/_underscore/features/acl-permission-chain.md
+  - ../../../2.0/apps/toga2-commerce/features/storefront-persona-gating-and-home-counts.md
 ---
 Giving a Compass **USA** person a login on the Canada TechHub portal: the guarded insert chain, the uuid role/persona mapping, and the worker2 guard that stops the next PEOPLE run switching them off.
 
@@ -62,7 +64,7 @@ Role ids differ between the two tenants. Look up `(SELECT r.id FROM Roles r WHER
 
 `PeopleFile.php` already keeps `ROLE_UUID_BASE` / `ROLE_UUID_COMPASS_BASE` / `ROLE_UUID_MANAGER` constants for the same reason — reuse those values.
 
-**Personas do not map by name either.** The two Canada admin personas: **Admin Canada** id 31, uuid `94eb162c-7adc-bc2e-66fa-c19fed1d1288` (widest catalogue — 213 items, all 35 bundles; this is Gina Prince's) and **Managers/VIPs** id 33, uuid `7961068f-8b31-1daf-5f52-0e45a09beb98` (168 items, 21 bundles). Persona **All** is id 1. Persona grants resolve through three sources, not just `Users_Personas` — see [Granting persona/bundle access](../../compass-usa/workflows/granting-persona-bundle-access.md).
+**Personas do not map by name either.** The two Canada admin personas: **Admin Canada** id 31, uuid `94eb162c-7adc-bc2e-66fa-c19fed1d1288` (widest for bundles + items: 213 items, all active bundles; this is Gina Prince's) and **Managers/VIPs** id 33, uuid `7961068f-8b31-1daf-5f52-0e45a09beb98` (168 items, 21 bundles, 13 categories). Persona **All** is id 1. **Persona 31 was NOT widest for categories** (see Gotchas) until `2026-10-15a` runs. Persona grants resolve through three sources, not just `Users_Personas` — see [Granting persona/bundle access](../../compass-usa/workflows/granting-persona-bundle-access.md).
 
 ### 4. Add the address to `ALWAYS_ACTIVE_EMAILS_CA`
 In `worker2/Worker/Client/Compass/PeopleFile.php`, **lowercase**, in `ALWAYS_ACTIVE_EMAILS_CA` — **not** `ALWAYS_ACTIVE_EMAILS_BOTH`. The BOTH list's `ensureCrossRegionUsersActive()` also forces `isActive = 1` on the **US** row every run, which would override a real US termination. `isEmailAlwaysActive()` lowercases its input, so a mixed-case constant entry never matches. Both layers of the guard are described in [PEOPLE-File User Lifecycle](../../compass-usa/features/people-file-user-lifecycle.md).
@@ -71,6 +73,8 @@ In `worker2/Worker/Client/Compass/PeopleFile.php`, **lowercase**, in `ALWAYS_ACT
 Run `sql-reviewer` on the SQL file and `php-reviewer` on the PeopleFile change, then give the developer numbered run steps (SQL file + environment order, then the worker2 deploy).
 
 ## Gotchas
+- **"Admin Canada" (31) alone showed only 2 categories (found 2026-10-15, TRUE-82848).** Storefront categories = `Personas_Assortments` rows for any of the user's personas, not bundles/items. Persona 31 had all bundles + items but only assortments 17 (APC Battery Back-UPs) and 18 (Webcams), so James Fuller (CA user 31583, persona 31 only) saw 2 of 16 categories. Gina Prince / Caleb Moore never noticed because their persona 33 adds 13 categories. Fix: `dbchanges2/Client_CompassCanada/2026-10-15a - AdminCanadaPersonaAllAssortments.sql` links persona 31 (by uuid) to every active assortment and drops a duplicate 18 row; verify expects 16 links. **Not yet run in any env** (beta had the same gap). Until it runs, give a hand-added admin persona 33 too, or check `Personas_Assortments` for the chosen persona.
+- **A NULL `Users.locationId` does not hide catalogue.** Bundle/item ACL expressions (`AclRecordExpressions` 251 items, 253 bundles) still pass through `Users_Personas`.
 - **`Client_CompassCanada.Users` has no `username`, `isSuperUser`, `personaId` or `roleId` column.** Access is entirely `Users_Roles` + `Users_Personas`. The login/personnel username is `c_hrEmpUsername`, stored lowercase.
 - **Leave `Users.password` NULL.** Login is SSO on the email address: only **45 of 28,788** `Client_CompassCanada` users hold a password, and the US rows for these people are NULL too.
 - **`Users.email` uses a case-insensitive collation**, so the stored case does not affect matching — `Client_Compass` often stores these addresses uppercase while Canada stores them lowercase.
@@ -86,3 +90,4 @@ Run `sql-reviewer` on the SQL file and `php-reviewer` on the PeopleFile change,
 
 ## Change history
 - 2026-09-28 — Created from the James Fuller hand-add; records the uuid role/persona map and the `ALWAYS_ACTIVE_EMAILS_CA`-not-BOTH rule (bala)
+- 2026-10-15 — Persona 31 had only 2 categories; corrected the "widest catalogue" claim, added the assortment fix (TRUE-82848) (bala)

package/knowledge/clients/compass-usa/features/approval-decision-flow.md

@@ -18,6 +18,7 @@ files:
   - dbchanges2/Client_Compass/2026-09-10b - RegisterApprovalDecisionPrePostInterceptor.sql
   - dbchanges2/Core/2026-10-09a - ManagerAutoApproveSettings.sql
   - dbchanges2/Client_Compass/2026-10-09a - ManagerAutoApproveSettingsSeed.sql
+  - dbchanges2/Client_Compass/2026-10-15a - VipAutoApproveOptOut.sql
 related:
   - mr-ma-order-approval-and-status.md
   - ../../../2.0/apps/toga25-supply/features/action-button-rule-engine.md
@@ -103,7 +104,12 @@ Data (all ids identical in prod, dev-sandbox, client-sandbox):
 - `dbchanges2/Client_Compass/2026-10-09a - ManagerAutoApproveSettingsSeed.sql` — `PersonaGlobalSettings` persona **35** (VIP Role) / setting 18 = `'5000'`; `UserGlobalSettings` user 60817 / setting 19 = `'1'`. Literal ids, no Core reference.
 - **Release order: Core SQL → Client_Compass SQL → deploy `_underscore`.** Code first = ALL VIP auto-approval stops until seeded.
 - Persona 35 is a safe stand-in for `c_isVip`: PeopleFile grants it to every VIP and removes it when VIP is dropped (prod: 2269/2269 active VIPs hold it, no non-VIP does) — see [Persona model](persona-model-and-levy-gating.md). Replay of the last 5,184 prod manager decisions: old rule 1,663 auto-approved, new 1,662; the only difference is user 60817.
-- To change a limit: edit the persona's setting-18 row (or seed one on another persona). To exempt one manager: add their setting-19 = `'1'` row.
+- To change a limit: edit the persona's setting-18 row (or seed one on another persona).
+- **To stop auto-approve for a manager (recurring "remove VIP auto approval" request):** add a setting-19 = `'1'` row; clearing `c_isVip` does nothing. Steps:
+  1. Find the user in **prod** `Client_Compass.Users` by **email** (request names often differ; duplicate/inactive accounts exist, pick the active one).
+  2. New `dbchanges2/Client_Compass/` file: one guarded `INSERT ... SELECT ... FROM DUAL WHERE NOT EXISTS` per user into `UserGlobalSettings` (`settingId 19`, `value '1'`, random v4 uuid literal), verify SELECT at end.
+  3. File is **prod-only**: `Users.id` differs per environment (settings/persona ids do not).
+  - Opted out so far (prod, 9 rows): 60817 (`2026-10-09a`); 60814, 60836, 60818, 60835, 60843, 60840, 60839, 43717 (`2026-10-15a - VipAutoApproveOptOut.sql`, TRUE-82852).
 
 Evaluated in exactly three places, all calling the shared check:
 - **(a) Order creation** — `_Model_Compass_SalesOrder::postPost`, inside `elseif (!empty($managerUserUuid))` (manager = delegate or requester's `Users.supervisorUserId`).
@@ -202,6 +208,7 @@ When a step-2 (Manager) decision is reassigned, `_swapManagerEmailAddress()` upd
 - **The upstream cause of an unassigned step 2 is a user saved with no `supervisorUserId`.** The admin add-user screen allows saving a user without one, and the PEOPLE-file import may or may not backfill it later. That data hole feeds both the `!$hasManager` wipe above and the never-created step-2 decision at order creation. Not fixed — the guard only stops the order being *stranded*, it does not give it a manager.
 
 ## Change history
+- 2026-10-15 — Opted 8 more managers out of auto-approve via setting 19; recorded the opt-out procedure (TRUE-82852). (bala)
 - 2026-10-15 — postPut re-picks the step-2 manager only on a real "order for" contact change, detected in prePut via `$api->passThrough` (TRUE-82727, `_underscore` PR #771). (bala)
 - 2026-10-09 — Manager auto-approve moved from `c_isVip` + hardcoded 5000 to persona setting 18 (limit) + user setting 19 (opt-out); postPut now compares subtotal (TRUE-82608). (bala)
 - 2026-10-06 — Recorded that no delegate + no supervisor saves an order with no step-2 decision, and that the commerce cart now blocks it (TRUE-82423). (bala)

package/knowledge/clients/compass-usa/features/contact-email-resolution.md

@@ -6,11 +6,12 @@ project: _Underscore
 client: compass-usa
 type: client-feature
 status: active
-updated: 2026-09-16
+updated: 2026-10-15
 owners: ["bala"]
 files:
   - _underscore/Model/Compass/PurchaseOrder.php
   - worker/crons/toga2/compass/update_salesorder_status_from_odp.php
+  - worker/crons/toga2/compass/send_delivered_email.php
 related:
   - ./mits-po-to-so-item-linking.md
   - ./people-file-user-lifecycle.md
@@ -81,11 +82,14 @@ The remaining ~42,900 crossed contacts were NOT mass-repaired. Consumers carry t
 
 ## Gotchas
 - **⚠ The pointer is crossed on ~14% of Compass contacts — treat an unguarded read as a bug.** Applies to reports, exports, notification crons, api2 payload interceptors, anything.
-- **A `Users` row is a different lookup and does not have this problem.** `Users.email` is keyed by `Users.contactId` directly. Where both exist, prefer `Users.email` and fall back to the guarded `ContactEmailAddresses` read — that is the `IFNULL(Users.email, ContactEmailAddresses.emailAddress)` precedence used by the in-transit cron. EDI-created MR orders have **no** `Users` row at all, which is why the fallback exists.
+- **A `Users` row is a different lookup and does not have this problem.** `Users.email` is keyed by `Users.contactId` directly. Where both exist, prefer `Users.email` and fall back to the guarded `ContactEmailAddresses` read — that is the `IFNULL(Users.email, ContactEmailAddresses.emailAddress)` precedence used by the in-transit cron. EDI-created MR orders have **no** `Users` row at all, which is why the fallback exists. **But one contact can have several `Users` rows, some with NULL email** — a bare `JOIN Users ON Users.contactId = …` fans out to one row per user; pick one active emailable user with a single-user subquery (`MAX(id)` pattern in the [delivered cron gotcha](../../../1.0/apps/worker/features/compass-partial-in-transit-delivered-emails.md)).
 - **`_Model_Compass_PurchaseOrder`'s contact lookup still has no ownership guard** (as of 2026-09-04). Fixing it there stops *new* crossings; the existing 42,926 remain either way.
 - **Compass Canada shares the model** (`Model/Compass/Canada/PurchaseOrder.php` inherits the parent), so the same lookup shape runs against `Client_CompassCanada`. Not measured there.
 - Duplicate-contact creation and duplicate-**user** creation are separate problems with separate causes — the `Users` duplicates come from the PEOPLE-file reactivation window, see [PEOPLE-file user lifecycle](./people-file-user-lifecycle.md).
 
+## Change history
+- 2026-10-15 — Noted duplicate `Users` rows per contact fan out a `Users.contactId` join; pick one emailable user (TRUE-82846). (bala)
+
 ## Related
 - [MITS PO → SO item linking](./mits-po-to-so-item-linking.md)
 - [PEOPLE-file user lifecycle](./people-file-user-lifecycle.md)

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

@@ -5,7 +5,9 @@
 | [TOGA Technology Website Architecture](architecture.md) | Public TOGA Technology marketing site — standalone React/TS SPA (no PHP framework); open for stack, bootstrap, routing, page layout, integrations, build/deploy. |
 | [Careers Section — Live Paylocity Job Openings (About page + /v2/campaigns/jobs proxy)](features/careers-paylocity-job-openings.md) | togatech About page "Join Our Team" section — live Paylocity jobs via unauthenticated `GET /v2/campaigns/jobs` record-script proxy; open for the fetch→proxy→map |
 | [NavV2 Global Nav — menus, panel shell, scroll reveal, Talos FAB](features/navv2-global-nav.md) | togatech NavV2 header (designer "phase one"): data-driven menus, one shared panel shell + WebGL canvas, `data-nav-reveal` scroll hide/show, opt-in `data-nav-pin |
-| [SEO / AEO / GEO — Prerendering, Single-Source Meta & Structured Data](features/seo-aeo-geo-prerender.md) | togatech SEO/AEO/GEO — build-time Puppeteer prerender + single-source per-page meta + JSON-LD; open for the robots-gating de-index bug and Amplify build require |
-| [Talos Product Page (/talos) — ported designer prototype](features/talos-product-page.md) | togatech `/talos` Talos AI product page, ported from a designer HTML/JSX/CSS prototype; open for the design-port CSS approach, re-porting a new design drop, laz |
+| [Platform Product Page (/our-platform) — ported designer prototype](features/platform-product-page.md) | togatech `/our-platform` TOGa Platform product page, ported from designer prototype `our-platform-v5`; open for the page-root-as-`<html>` rule, effect-order rul |
+| [SEO / AEO / GEO — Prerendering, Single-Source Meta & Structured Data](features/seo-aeo-geo-prerender.md) | togatech SEO/AEO/GEO — build-time Puppeteer prerender + hydration, code-split routes (`lazyRoute`), single-source per-page meta + JSON-LD; open for the robots d |
+| [Talos Product Page (/talos) — ported designer prototype](features/talos-product-page.md) | togatech `/talos` Talos AI product page, ported from a designer HTML/JSX/CSS prototype; open for its talos.css port edits, section notes, open port work and pla |
 | [Creating Pull Requests on togatech](workflows/creating-pull-requests.md) | Open a PR on `agilantsolutions/togatech` — `gh` CLI lacks `read:org`, so use a raw GitHub REST call with the keychain token; base is `_production`. |
+| [Porting a Designer Prototype to a togatech Page](workflows/designer-prototype-port.md) | togatech procedure for turning a designer HTML/JSX/CSS prototype into a live page (`/talos`, `/our-platform`): where drops and port tools live, generated prefix |
 | [Running togatech Locally & Verifying a Page Without Cypress](workflows/local-dev-and-headless-verification.md) | Get togatech running on a dev machine and verify a data-driven section without Cypress — `npm install` first, `lint` is dead, Cypress 15 fails on Windows. |

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

@@ -6,12 +6,13 @@ project: TOGA Technology Website
 client: shared
 type: architecture
 status: active
-updated: 2026-09-25
+updated: 2026-10-15
 owners: [jcardinal, tcox]
 files:
   - togatech/src/main.tsx
   - togatech/src/App.tsx
   - togatech/src/routes.tsx
+  - togatech/src/utils/lazyRoute.tsx
   - togatech/src/lib/api.ts
   - togatech/src/lib/contentful.ts
   - togatech/src/themeConfig/ThemeContext.tsx
@@ -20,16 +21,18 @@ files:
   - togatech/src/components/NavV2/navRoutes.ts
   - togatech/src/components/templates/AppLayout/AppLayout.tsx
   - togatech/src/routes.config.json
-related: []
+related:
+  - features/seo-aeo-geo-prerender.md
+  - workflows/designer-prototype-port.md
 ---
 
 Public TOGA Technology marketing site — standalone React/TS SPA (no PHP framework); open for stack, bootstrap, routing, page layout, integrations, build/deploy.
 
 ## Summary
 
-Public-facing TOGA Technology corporate/marketing website. Standalone single-page React app — uses **neither** PHP framework (1.0 `App_` nor 2.0 `_underscore`), hence the `standalone/` partition. Consumes TOGA backend services (email + Talos AI API) over HTTP, pulls editorial content from Contentful, ships **no server code** — builds to static assets served from `dist/`. Local path in Claude memory (`repo-path-togatech`), not here.
+Public-facing TOGA Technology corporate/marketing website. Standalone single-page React app — uses **neither** PHP framework (1.0 `App_` nor 2.0 `_underscore`), hence the `standalone/` partition. Consumes TOGA backend services (email + Talos AI API) over HTTP, pulls editorial content from Contentful, ships **no server code** — builds to static, prerendered assets served from `dist/`. Local path in Claude memory (`repo-path-togatech`), not here.
 
-**Critical rules:** All config comes from Vite `VITE_*` env vars (values in `.env`, never in docs). `togatech/.env` is currently **tracked in git** with live `VITE_*` creds (Contentful token, Talos API key) — treat as committed secrets. Build outputs to `dist/`; the `robotsPlugin` swaps the robots file at build time.
+**Critical rules:** All config comes from Vite `VITE_*` env vars (values in `.env`, never in docs). `togatech/.env` is currently **tracked in git** with live `VITE_*` creds (Contentful token, Talos API key) — treat as committed secrets. Code-split a prerendered route only through `lazyRoute` + `CODE_SPLIT_ROUTES` — plain `React.lazy` + `<Suspense>` or the router's `lazy` blanks the page on hydrate (features/seo-aeo-geo-prerender.md).
 
 ## Stack
 
@@ -38,13 +41,15 @@ Public-facing TOGA Technology corporate/marketing website. Standalone single-pag
 - **React Router 7.9** via `createBrowserRouter` (data-router API).
 - **@agilant/toga-blox** (internal design-system / component + API library) — shared UI and the `apiGet` HTTP helper (`@agilant/toga-blox/dist/api/apiFunctions`).
 - **FontAwesome Pro** icons.
+- **three.js 0.184.0** (+ `@types/three`, pinned) — only via `await import()` inside engine effects; rules in features/platform-product-page.md.
+- **Font:** Plus Jakarta Sans, self-hosted variable woff2 (`src/assets/fonts/`, weights 200–800 + italic, `@font-face` in `src/styles/index.css`) — no Google Fonts link. `html, body` get `-webkit-font-smoothing: antialiased`, `-moz-osx-font-smoothing: grayscale`, `text-rendering: optimizeLegibility` site-wide.
 - **Cypress 15** for e2e.
 
 ## Application bootstrap
 
 `src/main.tsx` → `src/App.tsx` → `src/routes.tsx`.
 
-- `main.tsx` mounts `<App/>` inside `HelmetProvider` (react-helmet-async, per-page SEO `<head>`) and `StrictMode`.
+- `main.tsx` mounts `<App/>` inside `HelmetProvider` (react-helmet-async, per-page SEO `<head>`) and `StrictMode`. Prerendered path → `hydrateRoot` (after preloading a code-split route's chunk); else `createRoot`.
 - `App.tsx` wires global providers, in order:
   1. `PersistQueryClientProvider` — TanStack **React Query** client persisted to `localStorage` (persister key `"commerce"`); default query `staleTime` 24h.
   2. `ThemeProvider` (`src/themeConfig/ThemeContext.tsx`) — applies active theme from `themes.json` (color/btn token sets, e.g. `DEFAULT`).
@@ -61,18 +66,18 @@ Public-facing TOGA Technology corporate/marketing website. Standalone single-pag
 | `/` (index) | `pages/Home` |
 | `/about` | `pages/About` |
 | `/what-we-do` | `pages/WhatWeDo` |
-| `/our-platform` | `pages/OurPlatform` |
+| `/our-platform` | `pages/OurPlatform` (code-split — features/platform-product-page.md) |
 | `/contact` | `pages/Contact` |
-| `/talos` | `pages/Talos` (code-split — see features/talos-product-page.md) |
+| `/talos` | `pages/Talos` (code-split — features/talos-product-page.md) |
 | `/privacy-policy` | `pages/PrivacyPolicy` |
 | `/terms-and-conditions` | `pages/TermsAndConditions` |
 | every `STUB_ROUTES` path | `pages/Stub` placeholder (`<StubPage title>`) |
 | `*` | `pages/NotFound` |
 
 - **Nav destinations are data** in `components/NavV2/navRoutes.ts`: `LIVE_ROUTES` (real pages) and `STUB_ROUTES` (placeholder until built — delete the line to retire a stub). Blog routes are commented out.
-- **Prerender list:** `src/routes.config.json` lists the static routes to prerender + sitemap. Add every new live route there (rules: features/seo-aeo-geo-prerender.md).
-- Pages are imported eagerly except `/talos` (`React.lazy` + `<Suspense>` inside the route Component — never the router's `lazy`, it breaks hydration).
-- **AppLayout → page contract:** `<Outlet context={{ openTalosChat }} />`; pages read it via `useAppLayoutContext()` (`AppLayout/appLayoutContext.ts`) to open the global Talos chat modal. `ROUTES_WITH_OWN_FOOTER` (only `/talos`) hides the old site footer on pages that render the redesigned one.
+- **Prerender list:** `src/routes.config.json` lists the static routes to prerender + sitemap. Add every new live route there (checklist: features/seo-aeo-geo-prerender.md).
+- Pages are imported eagerly except the code-split ones (`/talos`, `/our-platform`): `lazyRoute` (`utils/lazyRoute.tsx`) + `CODE_SPLIT_ROUTES` in `routes.tsx`; `main.tsx` preloads the current one before hydrating.
+- **AppLayout → page contract:** `<Outlet context>` carries `openTalosChat()`, `askTalos(question)`, `closeTalosChat()`, `isTalosChatOpen`; pages read it via `useAppLayoutContext()` (`AppLayout/appLayoutContext.ts`). AppLayout owns the one Talos chat modal — never mount a second. `ROUTES_WITH_OWN_FOOTER` / `ROUTES_WITH_OWN_LAUNCHER` (`/talos`, `/our-platform`) hide the old site footer / NavV2 FAB on pages that render `FooterV2` / `TalosLauncher`; retire them when the redesign goes site-wide.
 - A Cypress-only test route swaps `WhatWeDoPage` for a throwing component to exercise the error boundary (`VITE_CY_TEST` / `window.Cypress`).
 
 ## Page structure — MVVM per page
@@ -90,17 +95,18 @@ pages/Home/
 
 - **viewModel** holds data fetching (React Query hooks), form field defs (`FIELDS`), behavior.
 - **view** is presentational. Keeps page logic testable and out of JSX.
+- Redesigned pages (`Talos`, `OurPlatform`) are ports of designer prototypes: one generated page-scoped CSS file + `view/sections/` + engine hooks — workflows/designer-prototype-port.md.
 
 ## Shared layers
 
-- `src/components/` — reusable UI (NavV2 global nav incl. `TalosFab`, Header, Footer, Hero, Carousel/Swiper wrappers, Modal, TalosChat + TalosChatInput, motion/animation helpers, animated SVGs, etc.).
+- `src/components/` — reusable UI: NavV2 global nav (incl. `TalosFab`), Header, Footer (old) and `FooterV2` (redesign), `TalosLauncher` (page orb + guide), `SiteFaq`, `Reveal`, `TalosMark`, Hero, Carousel/Swiper wrappers, Modal, TalosChat + TalosChatInput, motion/animation helpers, animated SVGs, etc.
 - `src/components/templates/` — layout primitives: `AppLayout` (router root chrome; Outlet context + `appLayoutContext.ts`), `DefaultContainer`, `MarginContainer`, `GlowingContainer`, `ErrorContainer`.
 - `src/lib/` — data/integration:
   - `api.ts` — `useSendEmail` (contact form) and `postTalosMessage` (AI chat).
   - `contentful.ts` — Contentful delivery client (`createClient`).
   - `talosSystemPrompt.ts` — Talos chat system prompt.
   - `types.ts` — shared API/domain types (`ChatMessage`, `OutputField`, `ChatAPIError`…).
-- `src/utils/` — helpers (`emphasizeText`, `getFontAwesomeIcon`, `animateSections`) and hooks (`useFocusTrap`, `useLockBgScroll`).
+- `src/utils/` — helpers (`emphasizeText`, `getFontAwesomeIcon`, `animateSections`, `lazyRoute`, `isPrerender`, `isPinnedSceneLocked`) and hooks (`useFocusTrap`, `useLockBgScroll`, `useRootStyles`, `useBtnSpot`).
 - `src/themeConfig/` — `ThemeContext.tsx`, `themes.json`, `types.ts`.
 
 ## External integrations
@@ -114,9 +120,9 @@ All via Vite `VITE_*` env vars (values in `.env`, never in repo docs):
 
 ## Build, environments, deploy
 
-- `package.json` scripts: `dev`, `togatech` (dev with `--host togatech`), `build` (`tsc && vite build`), `buildBeta` (`--mode beta`), `buildGamma` (`--mode gamma`), `preview`, `lint` (ESLint — non-functional: no eslint dependency or config; see workflows/local-dev-and-headless-verification.md). `build` also runs the Puppeteer prerender (see features/seo-aeo-geo-prerender.md).
+- `package.json` scripts: `dev`, `togatech` (dev with `--host togatech`), `build` (`tsc && vite build` + Chrome install + Puppeteer prerender — features/seo-aeo-geo-prerender.md), `buildBeta` (`--mode beta`), `buildGamma` (`--mode gamma`), `preview`, `lint` (ESLint — non-functional: no eslint dependency or config; see workflows/local-dev-and-headless-verification.md).
 - Multi-environment: `development`, `beta`, `gamma`, `production` (Vite modes).
-- Vite `base: "/"`, output to `dist/`, `publicDir: public`. A custom `robotsPlugin` copies `public/robots.prod.txt` or `public/robots.dev.txt` to `dist/robots.txt` at `closeBundle`, depending on prod detection (`NODE_ENV` + `VITE_ENV`).
+- Vite `base: "/"`, output to `dist/`, `publicDir: public` (Amplify serves it through S3/CloudFront). A custom `robotsPlugin` copies `public/robots.prod.txt` to `dist/robots.txt` only when Vite `mode === "production"`, else `robots.dev.txt` — never gate it on `NODE_ENV` (features/seo-aeo-geo-prerender.md).
 - `@` path alias → `./src` (Vite `resolve.alias`).
 - Dev server `allowedHosts: ["togatech"]` (matches the `togatech` host script).
 

package/knowledge/standalone/apps/togatech/features/navv2-global-nav.md

@@ -6,38 +6,30 @@ project: TOGA Technology Website
 client: shared
 type: feature
 status: active
-updated: 2026-10-12
+updated: 2026-10-15
 owners: ["tcox"]
 files:
   - togatech/src/components/NavV2/view/NavV2.tsx
   - togatech/src/components/NavV2/view/TalosFab.tsx
-  - togatech/src/components/NavV2/view/NavDestLink.tsx
   - togatech/src/components/NavV2/view/SilkCanvas.tsx
   - togatech/src/components/NavV2/view/panels/WhatPanel.tsx
   - togatech/src/components/NavV2/view/panels/CompanyPanel.tsx
-  - togatech/src/components/NavV2/view/panels/IndustriesPanel.tsx
-  - togatech/src/components/NavV2/view/panels/ResourcesPanel.tsx
   - togatech/src/components/NavV2/view/panels/PanelFooter.tsx
   - togatech/src/components/NavV2/navV2.module.css
-  - togatech/src/components/NavV2/types.ts
   - togatech/src/components/NavV2/navRoutes.ts
-  - togatech/src/components/NavV2/viewModel/useNavV2.ts
   - togatech/src/components/NavV2/viewModel/useNavReveal.ts
-  - togatech/src/components/NavV2/viewModel/useCompactViewport.ts
   - togatech/src/components/NavV2/viewModel/useRovingTabs.ts
-  - togatech/src/components/NavV2/viewModel/useDockedState.ts
   - togatech/src/components/NavV2/viewModel/FIELDS/NAVFIELDS.json
   - togatech/src/components/MobileNav/MobileNav.tsx
-  - togatech/src/styles/index.css
-  - togatech/public/assets/nav/logo-talos-ai.svg
-  - togatech/public/assets/nav/logo-toga-platform.svg
-  - togatech/tailwind.config.js
+  - togatech/src/utils/isPinnedSceneLocked.ts
 related:
   - ../architecture.md
   - talos-product-page.md
+  - platform-product-page.md
+  - ../workflows/designer-prototype-port.md
 ---
 
-togatech NavV2 header (designer "phase one"): data-driven menus, one shared panel shell + WebGL canvas, `data-nav-reveal` scroll hide/show, opt-in `data-nav-pinned` for sticky scenes, Talos FAB rules, design-anchor rule. Open before touching the nav or adding a full-screen sticky section.
+togatech NavV2 header (designer "phase one"): data-driven menus, one shared panel shell + WebGL canvas, `data-nav-reveal` scroll hide/show, opt-in `data-nav-pinned` for sticky scenes, Talos FAB rules, type-spec line-height rule, design-anchor rule. Open before touching the nav or adding a full-screen sticky section.
 
 ## Summary
 
@@ -57,7 +49,10 @@ Global header in `src/components/NavV2/` (MVVM: `view/`, `viewModel/`, menu data
 - `.panel[hidden]{display:none}` is required — `.panel{display:flex}` beats the `hidden` attribute.
 - `navPanelIn` slide-in plays on open (display none → flex restarts it); switching menu to menu does not replay it.
 
-**Type:** matches the designer type spec (see Gotchas). `navV2.module.css` resets the site-wide word-spacing inside the nav: `.root :where(p,h2,h3,h4,h5,h6,a,li,button){word-spacing:normal}` (same idea as `/talos` — see [talos-product-page.md](talos-product-page.md) Gotchas).
+**Type:** matches the "Mega-menu type spec" PDF (TRUE-82042; QC 186/186 rows, within 0.5px of the design). It supersedes the older `navigation-type-spec.md` — tcox: "go by the new pdf".
+- Nav root base type: weight 400, line-height 1.5, colour `#fff`, the spec's font stack (site font: [architecture.md](../architecture.md) Stack).
+- **An item with no stated line-height inherits 1.5** (the old spec's "normal" values are void). Exception: top-bar trigger buttons keep `line-height: normal` (the design's plain buttons).
+- `navV2.module.css` resets the site-wide word-spacing inside the nav: `.root :where(p,h2,h3,h4,h5,h6,a,li,button){word-spacing:normal}` (same as page ports — see [designer-prototype-port.md](../workflows/designer-prototype-port.md) Gotchas).
 
 **Mobile:** `MobileNav` closes on resize only when width > 1280 (`MOBILE_NAV_MAX_WIDTH_PX`), matching `tailwind.config.js` `md: {max:'1280px'}` (AppLayout: NavV2 `md:hidden`, hamburger `hidden md:block`).
 
@@ -68,11 +63,11 @@ Global header in `src/components/NavV2/` (MVVM: `view/`, `viewModel/`, menu data
 - Glass look (blur / grain / edge) only in `shown`.
 - `useCompactViewport.ts`: compact padding when viewport height ≤ 1000px.
 
-**Pinned scenes (opt-in):** a full-screen sticky scene must carry `data-nav-pinned` so the bar does not pop back during it. Current users: Home `Difference.tsx`, WhatWeDo `CardScroll.tsx`. Add the attribute to any new scroll-pinned section.
+**Pinned scenes (opt-in):** a full-screen sticky scene must carry `data-nav-pinned` so the bar does not pop back during it. `utils/isPinnedSceneLocked.ts` reads it for both the nav and the Talos guide (`TalosLauncher waitForPins` holds bubbles while a scene is locked). Current users: Home `Difference.tsx`, WhatWeDo `CardScroll.tsx`, `/our-platform` `.pfc-stage` and SolutionsStage `.pseq__pin`. Add the attribute to any new scroll-pinned section.
 
 **Section anchors:** `src/styles/index.css` has `:where(section[id]:not(#top)) { scroll-margin-top: 104px }` (zero specificity — a page rule overrides it freely).
 
-**Talos FAB (`TalosFab.tsx`):** a `<button>` that opens the global chat via `openTalosChat` (same as the bar pill) — not a `Link` to `/talos`. Visible only past one screen of scroll **and** while the bar is not `shown`; unfocusable while hidden. Ask Talos pill + FAB use the design's light-trail ring — no box-shadow glow in any state.
+**Talos FAB (`TalosFab.tsx`):** a `<button>` that opens the global chat via `openTalosChat` (same as the bar pill) — not a `Link` to `/talos`. Visible only past one screen of scroll **and** while the bar is not `shown`; unfocusable while hidden. Ask Talos pill + FAB use the design's light-trail ring — no box-shadow glow in any state. Pages in AppLayout `ROUTES_WITH_OWN_LAUNCHER` (`/talos`, `/our-platform`) hide the FAB and render `components/TalosLauncher` (orb + guide) instead.
 
 ## Gotchas
 
@@ -82,8 +77,9 @@ Global header in `src/components/NavV2/` (MVVM: `view/`, `viewModel/`, menu data
 - **Tailwind screens here are max-width (desktop-first):** `md:` means "≤ 1280px", not "≥ 768px".
 - **Tailwind line-height traps:** `text-xs/sm/base/lg` set their own line-height; `leading-normal` is `1.5`, not CSS `line-height: normal`. When the design says "normal", use `leading-[normal]`.
 - **Set logo size by inline style, not the `height` attribute** — Tailwind preflight `img{height:auto}` overrides it (the TOGa Platform SVG is 98x100, not square).
-- Nav type spec (sizes, weights, spacing, line-height, colour) is `navigation-type-spec.md`, attached to ClickUp TRUE-82043. Check nav type changes against it.
+- Nav type changes are checked against the "Mega-menu type spec" PDF (TRUE-82042), not the older `navigation-type-spec.md` (TRUE-82043).
 
 ## Change history
+- 2026-10-15 — Matched the "Mega-menu type spec" PDF: nav base type 400 / 1.5 / #fff, unstated line-heights inherit 1.5, trigger buttons stay normal; /our-platform pinned scenes; TalosLauncher pages hide the FAB (TRUE-82042 / TRUE-82652, tcox)
 - 2026-10-12 — Type spec match, Platforms logos, one shared panel shell + SilkCanvas (WebGL context leak fix), MobileNav closes only above 1280px (TRUE-82042, tcox)
 - 2026-10-05 — Phase-one redesign: 4 → 2 menus, `flatLinks[]`, Platforms/Company panels rebuilt, scroll reveal + `data-nav-pinned`, compact viewport, FAB visibility rules (tcox)

package/knowledge/standalone/apps/togatech/features/platform-product-page.md

@@ -0,0 +1,71 @@
+---
+title: Platform Product Page (/our-platform) — ported designer prototype
+framework: "standalone"
+repo: togatech
+project: TOGA Technology Website
+client: shared
+type: feature
+status: active
+updated: 2026-10-15
+owners: ["tcox"]
+files:
+  - togatech/src/pages/OurPlatform/OurPlatformPage.tsx
+  - togatech/src/pages/OurPlatform/ourPlatform.css
+  - togatech/src/pages/OurPlatform/viewModel/platformRoot.ts
+  - togatech/src/pages/OurPlatform/viewModel/pageSignals.ts
+  - togatech/src/pages/OurPlatform/viewModel/useLattice.ts
+  - togatech/src/pages/OurPlatform/viewModel/usePfCover.ts
+  - togatech/src/pages/OurPlatform/viewModel/three
+  - togatech/src/pages/OurPlatform/view/sections/ElectricGrid/ElectricGrid.tsx
+  - togatech/src/pages/OurPlatform/view/sections/CoreApps
+  - togatech/src/pages/OurPlatform/viewModel/FIELDS
+  - togatech/public/assets/platform
+  - togatech/cypress/e2e/ourPlatformPage/platformPage.cy.ts
+related:
+  - ../architecture.md
+  - ../workflows/designer-prototype-port.md
+  - talos-product-page.md
+  - seo-aeo-geo-prerender.md
+  - navv2-global-nav.md
+---
+
+togatech `/our-platform` TOGa Platform product page, ported from designer prototype `our-platform-v5`; open for the page-root-as-`<html>` rule, effect-order rules, three.js/WebGL engines, video weight, placeholder copy.
+
+## Summary
+
+`/our-platform` (`src/pages/OurPlatform/`) is a 13-section product page ported from the designer prototype `our-platform-v5` (TRUE-82652). It replaced the old OurPlatform page; the old page, `components/AccordionCard` and the 5 old specs in `cypress/e2e/ourPlatformPage/` were deleted — one smoke spec remains, `platformPage.cy.ts`. Port method: [designer-prototype-port.md](../workflows/designer-prototype-port.md). Layout: `view/sections/<Section>/`, `view/shared/` (`PlatformDot`, `TalosSecondaryBtn`), hooks and engines in `viewModel/`, three.js engines in `viewModel/three/`, copy in `viewModel/FIELDS/*.json`, assets in `public/assets/platform/` (~22 MB). Code-split, prerendered; renders `FooterV2`, `TalosLauncher` and the `platformSchema` JSON-LD.
+
+## How it works
+
+**Page root = the design's `<html>`** (`viewModel/platformRoot.ts`):
+- Every attribute and custom property the design set on `documentElement` (`data-pfc`, `data-pfc-state`, `data-grid`, `data-eg-tone`, `--tier-content`, `--lattice-mask`, …) is written on `.platformPage`, because `ourPlatform.css` maps `:root` / `html` / `body` onto it. Find the root with `getPlatformRoot()`.
+- Viewport reads (`clientWidth`, `innerHeight`) stay on `document.documentElement`.
+- Constant root vars (`PFC_ROOT_VARS`, `--lt-bright`) render in the root's `style`, so the prerender and the first client render match.
+
+**CSS:** `ourPlatform.css` is generated by `design-files/_port-tools/build-platform-css.cjs` (local only). Never hand-edit it in bulk — add an `EDITS` entry or a port addition and regenerate. Skipped design files: `nav-v2.css` (NavV2 is ported), `card-glow.css`, `solutions-b3-v5.css`.
+
+**Effect order (load-bearing):**
+- `useLattice` runs in the layout effect of the page's **first child**, `ElectricGrid`, so the grid tier exists before any section measures (React runs child layout effects first, in tree order). The page root's ref is not attached yet then, so it finds the root with `closest()`.
+- `pageSignals.ts` replaces the design's module globals (`heroVidCtl`, `lightApi`). The cover (`usePfCover`, layout effect) runs before the hero video loop and the cover light register (passive effects), so `pageSignals` keeps the last requested hero-sleep / cover-visible state and applies it when each registers.
+
+**three.js / WebGL:**
+- `three` 0.184.0 + `@types/three`, both pinned.
+- `three` is imported only by modules in `viewModel/three/`, and those load only via `await import("./three/<engine>")` inside an engine effect — never a static import (it would pull three.js into the page chunk), never under prerender, only near the viewport.
+- Engines dispose and call `renderer.forceContextLoss()` on cleanup. `renderer.debug.checkShaderErrors = false` — otherwise ANGLE/D3D precision warnings flood the console.
+- The design's WebGL custom elements are rebuilt as hooks on empty React hosts.
+
+**Layout integration:**
+- Listed in AppLayout `ROUTES_WITH_OWN_FOOTER` and `ROUTES_WITH_OWN_LAUNCHER`. `TalosLauncher` gets `leftHero={platformLeftHero}` (the cover rises over a pinned hero, so the nav docks late) and `waitForPins`.
+- Pinned scenes carry `data-nav-pinned`: `.pfc-stage` (the cover) and SolutionsStage `.pseq__pin`. NavV2 reveal and the Talos guide both read it — see [navv2-global-nav.md](navv2-global-nav.md).
+- The CoreApps app window raises the page root's `z-index` while open, so it covers NavV2 (the root has `isolation: isolate`).
+
+**Links:** design `contact.html` → `/contact` (also the placeholder `#book-roi-session`); `talos.html` → `/talos`. "Explore TOGa" (not wired in the design) scrolls to the cover and focuses `#modes`.
+
+**Open copy (2026-10-15):** FAQ Q2–Q6 answers not verified; ROI, Outcomes, app-window and Talos guide copy are placeholders.
+
+## Gotchas
+
+- **Video weight:** in a prod build on fresh Chrome the videos cost ~0.7s LCP and ~200–290 MB of Chrome memory. The design's two-copy crossfade downloads the hero video ~1.5×. Moving videos to a separate S3 bucket changes nothing — Amplify already serves `public/` through S3/CloudFront (same bytes, same memory). Real wins: re-encode `hero-loop-3.mp4` (13.5 MB), poster PNG → webp. Deferred by tcox to a later optimization pass. The site-wide JS bundle is the bigger LCP problem — see [seo-aeo-geo-prerender.md](seo-aeo-geo-prerender.md) Gotchas.
+
+## Change history
+- 2026-10-15 — Rebuilt /our-platform from designer prototype our-platform-v5; old page, AccordionCard and 5 old Cypress specs deleted (TRUE-82652, tcox)

package/knowledge/standalone/apps/togatech/features/seo-aeo-geo-prerender.md

@@ -6,85 +6,86 @@ project: TOGA Technology Website
 client: shared
 type: feature
 status: active
-updated: 2026-09-16
-owners: ["ajean", "jcardinal"]
+updated: 2026-10-15
+owners: ["ajean", "jcardinal", "tcox"]
 files:
   - togatech/vite.config.ts
   - togatech/scripts/prerender.mjs
   - togatech/src/routes.config.json
   - togatech/src/main.tsx
-  - togatech/src/App.tsx
+  - togatech/src/routes.tsx
+  - togatech/src/utils/lazyRoute.tsx
+  - togatech/src/utils/isPrerender.ts
   - 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/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
-related: []
+related:
+  - ../architecture.md
+  - talos-product-page.md
+  - platform-product-page.md
+  - ../workflows/creating-pull-requests.md
+  - ../../../standards/brand-naming.md
 ---
 
-togatech SEO/AEO/GEO — build-time Puppeteer prerender + single-source per-page meta + JSON-LD; open for the robots-gating de-index bug and Amplify build requirements.
+togatech SEO/AEO/GEO — build-time Puppeteer prerender + hydration, code-split routes (`lazyRoute`), single-source per-page meta + JSON-LD; open for the robots de-index bug, adding a route, and Amplify build requirements.
 
 ## Summary
 
-Makes togatech.com visible and citable to search engines **and** AI answer engines (ChatGPT/Perplexity/Claude search, Google AI Overviews). The site is a CSR-only Vite/React SPA, so non-JS crawlers saw an empty `<div id="root">`. This feature fixes a production de-indexing bug and adds **build-time prerendering** so every static route ships real HTML, plus single-source per-page meta and JSON-LD structured data. Shipped on branches `fix-seo-deindex-emergency` (PR #29) and `feature-seo-aeo-prerender` (PR #30); **merged into `_production` on 2026-06-19** (Contact page conflict resolved — see gotchas).
+Makes togatech.com visible and citable to search engines **and** AI answer engines (ChatGPT/Perplexity/Claude search, Google AI Overviews). The site is a CSR-only Vite/React SPA, so non-JS crawlers saw an empty `<div id="root">`. This feature fixes a production de-indexing bug and adds **build-time prerendering** so every static route ships real HTML, plus single-source per-page meta and JSON-LD structured data. Merged into `_production` 2026-06-19 (PRs #29, #30).
 
 ## How it works
 
 **Key files / entry points:**
-- `vite.config.ts` — `robotsPlugin()` now gates on **Vite `mode`** (was `NODE_ENV && VITE_ENV`).
+- `vite.config.ts` — `robotsPlugin()` gates on **Vite `mode`**.
 - `scripts/prerender.mjs` — post-build headless-Chrome (Puppeteer) snapshot; chained into the `build` script.
-- `src/routes.config.json` — single source of static route paths (consumed by the prerender; intended for sitemap too).
-- `src/main.tsx` — `hydrateRoot` when a route was prerendered, else `createRoot`.
+- `src/routes.config.json` — single source of static route paths (prerender + sitemap).
+- `src/main.tsx` — `hydrateRoot` when a route was prerendered, else `createRoot`; preloads a code-split route's chunk first.
+- `src/utils/lazyRoute.tsx` + `CODE_SPLIT_ROUTES` in `src/routes.tsx` — code-split routes that hydrate.
 - `src/components/SEO/{Seo.tsx,JsonLd.tsx,schema.ts}` — shared head + JSON-LD; per-page `meta` lives in each page's `viewModel/FIELDS/*.json`.
 
 **Mechanics:**
 1. **robots:** `robotsPlugin` copies `robots.prod.txt` only when `mode === "production"`; beta/gamma/dev get `robots.dev.txt` (`Disallow: /`). `robots.prod.txt` carries an explicit AI-bot allow-list (GPTBot, ClaudeBot, PerplexityBot, …) + `https://` sitemap.
-2. **prerender:** `npm run build` = `tsc && vite build && npx puppeteer browsers install chrome && node scripts/prerender.mjs` (the Chrome-install step was added 2026-06-19 — see gotchas). The script serves `dist/` (reading the original shell once, serving it for all nav routes), snapshots each route in headless Chrome, and writes `dist/<route>/index.html`. Runs in a real browser, so **no SSR/window guards needed**.
-3. **meta:** each page renders `<Seo {...FIELDS.meta} />` — title/description/keywords/canonical/OG/Twitter from one place per page; canonical/OG URLs derived from one `SITE_URL`. `<JsonLd>` (Helmet `<script type="application/ld+json">`) is baked into the snapshot.
-4. **structured data:** all JSON-LD now lives in **one module — `src/components/SEO/schema.ts`** (the single source of truth), derived from `FOOTERFIELDS.json` (socials/email/phone) and each page's FIELDS JSON, so editing footer/content updates schema automatically. Exports and their render sites (emitted via `<JsonLd>`/Helmet):
+2. **prerender:** `npm run build` = `tsc && vite build && npx puppeteer browsers install chrome && node scripts/prerender.mjs`. The script serves `dist/` (reading the original shell once, serving it for all nav routes), snapshots each route in headless Chrome, and writes `dist/<route>/index.html`. Runs in a real browser, so **no SSR/window guards needed**. Code-split routes also wait for their page root (`PAGE_READY_SELECTORS`, e.g. `[data-testid="platform-page"]`) — `#root > *` is already true once the layout mounts, so a slow chunk would snapshot an empty page area.
+3. **code-split hydration (`lazyRoute`):** `main.tsx` looks up the current path in `CODE_SPLIT_ROUTES` (lowercased, trailing slash stripped) and awaits its `preload()` before `hydrateRoot` (8s timeout, then hydrates anyway). The route's `Route` decides once per mount: a loaded module renders directly, with no `<Suspense>` in the tree; otherwise (client-side navigation) `React.lazy` + `<Suspense>`. `preload` and the lazy share one import promise; a failed import makes a fresh lazy so the next visit retries. `onRecoverableError` logs any hydration mismatch as `[hydrate] recoverable error…`.
+4. **meta:** each page renders `<Seo {...FIELDS.meta} />` — title/description/keywords/canonical/OG/Twitter from one place per page; canonical/OG URLs derived from one `SITE_URL`. `<JsonLd>` (Helmet `<script type="application/ld+json">`) is baked into the snapshot.
+5. **structured data:** all JSON-LD lives in **one module — `src/components/SEO/schema.ts`**, derived from `FOOTERFIELDS.json` (socials/email/phone) and each page's FIELDS JSON, so editing footer/content updates schema automatically. Exports and their render sites:
    - `organizationSchema` + `websiteSchema` → **AppLayout** (all pages).
    - `serviceSchemas` (4 `Service` nodes) → **WhatWeDoPage**.
    - `platformSchema` (`SoftwareApplication` for the TOGa Platform) → **OurPlatformPage**.
    - `aboutPageSchema` (`AboutPage`) + `personSchemas` (per leader) → **AboutPage**.
    - `contactPageSchema` (`ContactPage`) + `localBusinessSchemas` (per office, from `CONTACTPAGEFIELDS.map.locations`) → **ContactPage**.
    - **Entity graph linked by `@id`:** Organization is `${SITE_URL}/#organization`, WebSite `/#website`, logo `/#logo`. Service/Person/LocalBusiness reference the org via `provider`/`worksFor`/`parentOrganization` `@id`; AboutPage/ContactPage set `isPartOf` the website and `about` the org. Use `@id` cross-references — do not inline duplicate org nodes.
-   - `organizationSchema.logo` is an `ImageObject` (`@id` `/#logo`, `url`, `contentUrl`, `caption "TOGA Technology"`); width/height are intentionally omitted because the logo is an SVG.
-   - `personSchemas` de-dupes a leader who appears in both `boardMembers` and `members` in `ABOUTPAGEFIELDS`, keyed on lowercased trimmed name (a `Set`) — naive emission produced duplicate `Person` nodes.
+   - `organizationSchema.logo` is an `ImageObject` (`@id` `/#logo`, `url`, `contentUrl`, `caption "TOGA Technology"`); width/height omitted because the logo is an SVG.
+   - `personSchemas` de-dupes a leader who appears in both `boardMembers` and `members` in `ABOUTPAGEFIELDS`, keyed on lowercased trimmed name — naive emission produced duplicate `Person` nodes.
 
-**Data model.** None (static marketing site). All copy/meta/NAP/leaders come from `*FIELDS*.json`; structured data is derived from `FOOTERFIELDS.json`, `CONTACTPAGEFIELDS.json` (`map.locations`), and `ABOUTPAGEFIELDS.json` (`teamMembers`).
+**New route checklist:**
+1. Add the path to `src/routes.config.json` (prerender + sitemap list).
+2. A nav destination moves from `STUB_ROUTES` to `LIVE_ROUTES` in `NavV2/navRoutes.ts` (removing the stub line retires the placeholder page).
+3. A heavy page (own big CSS, canvas/WebGL) is code-split: `const x = lazyRoute(() => import(...))`, `Component: x.Route`, add it to `CODE_SPLIT_ROUTES`, give the page root a `data-testid` and add it to `PAGE_READY_SELECTORS` in `prerender.mjs`.
 
 ## Gotchas
 
+- **🔴 Code-split a prerendered route only through `lazyRoute` — never plain `React.lazy` + `<Suspense>`, never react-router's route `lazy`.** React 18.3 hydrates a `<Suspense>` boundary only from the `<!--$-->` comment markers React's server renderer writes; the Puppeteer snapshot is client DOM and has none. Hydration throws, the whole root re-renders on the client, and the page area is blank until the chunk loads (confirmed in `react-dom` source, CTO-reviewed). Router `lazy` without a `HydrateFallback` renders blank too.
+- **Every prerendered page still re-renders on load (pre-existing, open).** `/`, `/about` and the rest have a hydration mismatch starting in the shared layout / NavV2, so React throws away the snapshot and re-renders the whole root. Needs its own ticket. Shows in the console as the `[hydrate]` log.
 - **De-indexing bug (root cause):** `robotsPlugin` required `NODE_ENV && VITE_ENV==="production"`, but build scripts set neither → every build shipped `robots.dev.txt` (`Disallow: /`). **Do NOT gate robots on `NODE_ENV`** — `vite build` sets it to `production` for *every* mode, which would expose beta/gamma. Gate on Vite `mode`.
-- **`.npmrc` has `ignore-scripts=true`** → the `postbuild` lifecycle hook never fires. Prerender is therefore chained directly in the `build` script, not a `postbuild` hook.
+- **`.npmrc` has `ignore-scripts=true`** → the `postbuild` lifecycle hook never fires. Prerender is therefore chained directly in the `build` script.
 - **Prerender tooling:** `vite-react-ssg` supports React Router **6 only** (project is RR 7.9); `react-snap` is stale (2022) and won't launch on Node 24. Hence a custom Puppeteer snapshot.
-- **🔴 Chrome must be installed in the build (now wired in):** Amplify/CodeBuild's `npm ci` does **not** download a browser, so `puppeteer.launch()` fails with `Could not find Chrome (ver. …)` at `/root/.cache/puppeteer`. Fixed 2026-06-19 by adding `npx puppeteer browsers install chrome` to the `build` script immediately before `node scripts/prerender.mjs` (same default cache `launch()` resolves from). puppeteer 25 also requires **Node ≥ 22.12** — set the Amplify image accordingly. (The step re-downloads ~150 MB per build unless `/root/.cache/puppeteer` is cached.)
-- **🔴 `package-lock.json` must be committed:** Amplify preBuild runs `npm ci`, which refuses to run without a committed lockfile (`npm error code EUSAGE`) and will **not** generate one. The lockfile is not gitignored — it was simply never committed; `npm install` once and commit it.
-- **Contact page merge (2026-06-19):** when merging the SEO/AEO feature into `_production`, `ContactPage.tsx` conflicted. Resolution: keep production's reCAPTCHA conditional wrap (`GoogleReCaptchaProvider` mounts only when `VITE_RECAPTCHA_V3_SITE_KEY` is set) **and** the `<Seo>`/`<JsonLd>` components; drop the incoming `<Helmet>` block (superseded by `<Seo>`).
-- **Prerender fail-fast:** a route that never mounts (`#root > *` times out) aborts the build with `process.exit(1)` — otherwise it would snapshot the empty shell (no SEO/JSON-LD) and still exit 0.
+- **🔴 Chrome must be installed in the build:** Amplify/CodeBuild's `npm ci` does **not** download a browser, so `puppeteer.launch()` fails with `Could not find Chrome (ver. …)` at `/root/.cache/puppeteer`. Fixed by `npx puppeteer browsers install chrome` in the `build` script right before `node scripts/prerender.mjs`. puppeteer 25 needs **Node ≥ 22.12** — set the Amplify image accordingly. (~150 MB download per build unless `/root/.cache/puppeteer` is cached.)
+- **🔴 `package-lock.json` must be committed:** Amplify preBuild runs `npm ci`, which refuses to run without a committed lockfile (`npm error code EUSAGE`).
+- **Prerender fail-fast:** a route that never mounts (`#root > *` or its ready selector times out) aborts the build with `process.exit(1)` — otherwise it would snapshot the empty shell and still exit 0.
 - **🔴 Hosting requirement:** CloudFront/S3 must serve each prerendered `dist/<route>/index.html` for its path; a blanket SPA rewrite to root `index.html` serves the empty shell and defeats the prerender.
-- **og:image dedupe:** static OG/Twitter tags were removed from `index.html` because `<Seo>` emits per-page ones (Helmet appends rather than replacing pre-existing static tags → duplicates otherwise).
-- **Verified data corrections:** real positioning is *integrated IT services + the ERA TOGa Platform*; real socials are LinkedIn `/toga-tech` + YouTube + Instagram (no Twitter/GitHub/Crunchbase); contact is `website@togatech.com` / `+1 (212) 736-0111`; **5** offices. Prior planning docs had several wrong specifics — verify schema/llms.txt against FIELDS before shipping.
-- **Build size:** JS bundle is ~14.8 MB (4.9 MB gzip) — a real CWV/LCP risk. Only `/talos` is code-split so far.
-- **🔴 Code-split a prerendered route with `React.lazy` + `<Suspense>` inside the route `Component` — never react-router's route `lazy`.** Router `lazy` without a `HydrateFallback` renders blank and throws away the prerendered HTML; a Suspense boundary keeps the server HTML until the chunk arrives. Pattern: `TalosRoute` in `routes.tsx`.
 - **🔴 Hooks must never append child nodes into React-owned elements.** The snapshot captures the appended nodes → hydration mismatch. Render a host element with `dangerouslySetInnerHTML={{__html:""}}` and clear it on start and cleanup.
-- **Prerender UA tag:** `prerender.mjs` sets a user agent containing `TOGAPrerender`. `App.tsx` skips analytics on it; canvas/animation engines must skip start on it too (e.g. `useTalosSparks.ts`).
-- **New route checklist:** add it to `src/routes.config.json` (prerender + sitemap list); a nav destination also moves from `STUB_ROUTES` to `LIVE_ROUTES` in `NavV2/navRoutes.ts` (removing the stub line retires the placeholder page).
-- **FIELDS JSON is component-coupled — no free-prose body slot:** each page's `*FIELDS*.json` is shaped to specific components (hero, cardScroll, businessProblems, kpi, carousel), so there is **no place to drop a long prose block**. An audit's "rewrite to 900 words" is not structurally possible without building new components — you can only sharpen titles/descriptions/keywords/card copy that already have slots. (`/our-platform` was left unchanged: it is already content-dense — 7 app modules + 4 stacks + testimonials + KPIs — and the original audit under-counted because that content is JS-rendered.)
-- **`personSchemas` duplicate guard:** a leader can be in both `boardMembers` and `members` in `ABOUTPAGEFIELDS` — `personSchemas` must de-dup by lowercased trimmed name, or it emits duplicate `Person` nodes.
-- **🔴 Brand name is "TOGA Technology" only — never "Agilant":** an earlier draft adding `alternateName: "Agilant"` / "(formerly Agilant)" to the org schema was explicitly reverted. Do not reintroduce "Agilant" in schema, copy, or meta. (Captured as a team brand standard — see Related docs.)
-
-## Related
-
-- standalone/apps/togatech/architecture.md (update its Build/deploy section once PR #30 merges — robotsPlugin gating + prerender step).
-- standalone/apps/togatech/features/talos-product-page.md — first code-split + canvas page under prerender.
-- standalone/apps/togatech/workflows/creating-pull-requests.md — how PRs get opened on this repo (gh CLI is unauthenticated; uses curl + osxkeychain token; base `_production`).
+- **Prerender UA tag:** `prerender.mjs` sets a user agent containing `TOGAPrerender`. `App.tsx` skips analytics on it; engines, timers and measured inline styles must skip too — use `isPrerender()` (`src/utils/isPrerender.ts`).
+- **og:image dedupe:** static OG/Twitter tags were removed from `index.html` because `<Seo>` emits per-page ones (Helmet appends rather than replacing pre-existing static tags → duplicates otherwise).
+- **Contact page merge (2026-06-19):** keep production's reCAPTCHA conditional wrap (`GoogleReCaptchaProvider` mounts only when `VITE_RECAPTCHA_V3_SITE_KEY` is set) **and** `<Seo>`/`<JsonLd>`; the old `<Helmet>` block is superseded by `<Seo>`.
+- **Verified data:** real positioning is *integrated IT services + the ERA TOGa Platform*; real socials are LinkedIn `/toga-tech` + YouTube + Instagram (no Twitter/GitHub/Crunchbase); contact is `website@togatech.com` / `+1 (212) 736-0111`; **5** offices. Prior planning docs had wrong specifics — verify schema/llms.txt against FIELDS before shipping.
+- **Brand name:** "TOGA Technology" only — an `alternateName: "Agilant"` draft was reverted. Rule: [brand-naming](../../../standards/brand-naming.md).
+- **Build size:** the main JS bundle is ~14.8 MB (4.9 MB gzip), site-wide — the biggest LCP problem, bigger than any page's videos. Only `/talos` and `/our-platform` are code-split.
+- **FIELDS JSON is component-coupled — no free-prose body slot:** each page's `*FIELDS*.json` is shaped to specific components, so there is no place to drop a long prose block. An audit's "rewrite to 900 words" needs new components; otherwise only sharpen titles/descriptions/keywords/card copy that already have slots.
 
 ## Change history
+- 2026-10-15 — Corrected the lazy + Suspense rule (it breaks hydration in React 18.3); added `lazyRoute` + chunk preload, prerender ready selectors, site-wide hydration mismatch finding (TRUE-82652, tcox)
 - 2026-09-25 — Added lazy-route, no-DOM-append, TOGAPrerender UA and new-route rules from the /talos build (tcox)

package/knowledge/standalone/apps/togatech/features/talos-product-page.md

@@ -6,60 +6,50 @@ project: TOGA Technology Website
 client: shared
 type: feature
 status: active
-updated: 2026-10-12
+updated: 2026-10-15
 owners: ["tcox"]
 files:
   - togatech/src/pages/Talos/TalosPage.tsx
   - togatech/src/pages/Talos/talos.css
   - togatech/src/pages/Talos/viewModel/useTalosSparks.ts
+  - togatech/src/pages/Talos/viewModel/talosSparksRoute.ts
   - togatech/src/pages/Talos/viewModel/useGlassPanes.ts
   - togatech/src/pages/Talos/viewModel/useTalosPanelSky.ts
   - togatech/src/pages/Talos/viewModel/useTalosSubnav.ts
   - togatech/src/pages/Talos/viewModel/FIELDS
-  - togatech/src/pages/Talos/view/sections/TalosChoosing/TalosChoosing.tsx
-  - togatech/src/pages/Talos/view/shared/Reveal.tsx
   - togatech/src/pages/Talos/view/sections/TalosHero
-  - togatech/src/pages/Talos/view/sections/TalosVoice
+  - togatech/src/pages/Talos/view/sections/TalosFaq/TalosFaq.tsx
+  - togatech/src/pages/Talos/view/sections/TalosChoosing/TalosChoosing.tsx
   - togatech/src/pages/Talos/view/sections/TalosGovernance
-  - togatech/src/routes.tsx
-  - togatech/src/components/templates/AppLayout/AppLayout.tsx
-  - togatech/src/components/templates/AppLayout/appLayoutContext.ts
-  - togatech/src/components/NavV2/view/TalosFab.tsx
 related:
   - ../architecture.md
+  - ../workflows/designer-prototype-port.md
+  - platform-product-page.md
   - seo-aeo-geo-prerender.md
   - navv2-global-nav.md
 ---
 
-togatech `/talos` Talos AI product page, ported from a designer HTML/JSX/CSS prototype; open for the design-port CSS approach, re-porting a new design drop, lazy-load + prerender rules, page-owned footer, opening the Talos chat from a page.
+togatech `/talos` Talos AI product page, ported from a designer HTML/JSX/CSS prototype; open for its talos.css port edits, section notes, open port work and placeholder copy.
 
 ## Summary
 
-`/talos` is a 15-section product page (`src/pages/Talos/`) ported from a designer prototype (static HTML + in-browser JSX + CSS). Design drops are temporary and never committed — latest at `togatech/project_html/uploads/New TOGA WEBSITE/TOGA Website/` (untracked; first drop was `_design/talos/`). Standard MVVM page layout: `view/sections/<Section>/` (incl. `TalosSparks` canvas backdrop and `TalosFooter`), `view/shared/Reveal.tsx`, `viewModel/use*.ts` hooks, copy in `viewModel/FIELDS/*.json`, images in `public/assets/talos/`. Live route, prerendered, in the sitemap list.
+`/talos` is a 15-section product page (`src/pages/Talos/`) ported from a designer prototype. Port method (drops, generated CSS, page root as `<html>`, shared pieces): [designer-prototype-port.md](../workflows/designer-prototype-port.md). Layout: `view/sections/<Section>/` (incl. the `TalosSparks` canvas backdrop), `viewModel/use*.ts` hooks, copy in `viewModel/FIELDS/*.json`, images in `public/assets/talos/`. Renders the shared `FooterV2` and `TalosLauncher` (moved out of this page to `src/components/` in TRUE-82652, no behaviour change). Code-split, prerendered, in the sitemap list.
 
 ## How it works
 
-**CSS port (the reusable approach for any designer prototype):**
-- All design CSS is concatenated **in original cascade order** into one plain file, `talos.css`, every selector prefixed `.talosPage `. `:root` / `html` / `body` selectors map to `.talosPage`.
-- Generated by a postcss prefix+concat script, `build-talos-css.cjs`, that lives **outside the repo** (session scratchpad, not `scripts/`). If it is lost, re-create it before the next design CSS change — never hand-edit a regenerated `talos.css` in bulk.
-- After regenerating, re-apply the port edits: add any design token the CSS uses but our copy lacks (the first port missed `--ease-enter`, so `.reveal` / `.tlh-enter` / `.tpl-rev` had no valid transition); drop `.needs-dev*`, `.tvq*`, and design `.talos-fab{display:none !important}` (it is for the design's orb launcher and would hide our NavV2 FAB until the orb is ported).
-- **Not a CSS module:** the design JS finds elements by raw class names/ids and sets keyframe names inline; CSS-module hashing breaks all of that. (CTO-reviewed choice.)
-- Design timing workarounds are kept on purpose: IntersectionObserver + rect-poll backstops and `setTimeout` retry chains (rAF / ResizeObserver can go silent on cold load). Animation loops pause off-screen and on hidden tab.
-- `<html>`-level styles (`overflow-x: clip` so `position: sticky` works — never `hidden`; `scroll-behavior: smooth`) are set in `useLayoutEffect` (`useRootStyles` in `TalosPage.tsx`) and **removed** on unmount, not "restored" (a prerendered snapshot already carries them, so the "previous" value is wrong).
-- **Reduced motion:** under `prefers-reduced-motion`, `useRootStyles` skips `scroll-behavior: smooth` and `useTalosSubnav` scrolls with `behavior: "instant"` — `"auto"` inherits the `<html>` smooth setting.
-
-**Code-split + prerender:** `routes.tsx` wraps the page in `React.lazy` + `<Suspense fallback={null}>` inside the route `Component`. Rules in [seo-aeo-geo-prerender.md](seo-aeo-geo-prerender.md). Page-specific: `useGlassPanes` `useFitGap` (56px under the lede) skips on the `TOGAPrerender` UA so the snapshot does not bake the crawler-viewport margin.
+**talos.css:** generated from the design CSS (`colors_and_type.css`, `site.css`, `talos-orb.css`, `talos.css`) under `.talosPage`. Its builder `build-talos-css.cjs` was not kept — re-create it in `design-files/_port-tools/` (model: `build-platform-css.cjs`) before the next design CSS change. Edits to carry over (also in the `talos.css` header): add the `--ease-enter` token (without it `.reveal` / `.tlh-enter` / `.tpl-rev` have no valid transition); drop `.needs-dev*` and `.tvq*`.
 
-**Layout hooks this page uses:**
-- **Opening the Talos chat:** AppLayout owns the global Talos chat modal and passes `<Outlet context={{ openTalosChat }} />`. Pages call `useAppLayoutContext().openTalosChat()` (`AppLayout/appLayoutContext.ts`). Use this — do not mount a second chat. The Hero's second button ("Ask Talos", `btn-talos-boxed is-lg is-hero`) uses it; there is no expanded chat mode yet.
-- **Own footer:** `ROUTES_WITH_OWN_FOOTER` in `AppLayout.tsx` (only `/talos` today, tcox's call) hides the old site footer; the page renders `TalosFooter`. Retire the list when the redesigned footer goes site-wide.
-- **Floating Talos button:** NavV2's `TalosFab` — see [navv2-global-nav.md](navv2-global-nav.md).
+**Page specifics:**
+- `useGlassPanes` `useFitGap` (56px under the lede) skips under prerender, so the snapshot does not bake the crawler-viewport margin.
+- Reduced motion: `useTalosSubnav` scrolls with `behavior: "instant"` — `"auto"` inherits the `<html>` smooth setting.
+- The Hero's second button ("Ask Talos", `btn-talos-boxed is-lg is-hero`) calls `openTalosChat` from the AppLayout context (see [architecture.md](../architecture.md) Routing) — never mount a second chat.
+- `TalosLauncher` gets `liftObstacles` = the closing CTA buttons + reCAPTCHA badge.
 
-**Section notes:** Voice sits at the end of `.tpanel2` as a `.tproof-*` stat + quote row (moved out of `.tpanel`). Governance `RAIL_COLUMNS = points.length` (7 points). PanelSky has no `.tp2-tw` twinkle; it fades over 360px to `PAGE_FILL`.
+**Section notes:** Voice sits at the end of `.tpanel2` as a `.tproof-*` stat + quote row. Governance `RAIL_COLUMNS = points.length` (7 points). PanelSky has no `.tp2-tw` twinkle; it fades over 360px to `PAGE_FILL`.
 
-**Routing:** `/talos` is in `LIVE_ROUTES` (`NavV2/navRoutes.ts`) and `src/routes.config.json`. Sub-pages `/talos/one|flow|engage` are still `STUB_ROUTES`.
+**Routing:** sub-pages `/talos/one|flow|engage` are still `STUB_ROUTES`.
 
-**Copy:** the design's default `COPY.katie` set (Katie signs off copy). Not production-ready yet (new ticket pending, as of 2026-10-12):
+**Copy:** the design's `COPY.katie` set (Katie signs off copy). Not production-ready (as of 2026-10-12):
 - `TALOSFAQFIELDS.json` — 6 answers are "[Answer not written. Needs Jeff.]"; "Certification three/four" are placeholders.
 - `TALOSVOICEFIELDS.json` — quote still flagged as placeholder.
 - `TalosChoosing` card CTAs ("Book a demo", "See TOGa Platform") are plain spans with no link.
@@ -67,23 +57,16 @@ togatech `/talos` Talos AI product page, ported from a designer HTML/JSX/CSS pro
 
 ## Port status (design drop 2, 2026-10)
 
-Done: batches 1–2 (CSS regen, copy, Hero ask, Voice move, Governance, PanelSky). Left:
+Done: CSS regen, copy, Hero ask, Voice move, Governance, PanelSky, orb launcher + guide bubbles (now shared `TalosLauncher`). Left:
 1. Compare rebuild — half-stars, info popover, key.
-2. FAQ two-column, 9 items, per-item ask. Then **delete the temporary bridge rules** under `#talos-faq:not(:has(.tfq-cols))` in `talos.css`.
-3. ProductLine "What can X do?" ask buttons + `useTalosSweep`.
+2. FAQ redesign: two columns, 9 items, per-item ask. Build it on the shared `SiteFaq` (`TalosFaq` today shares only `useFaqAccordion`). Then **delete the temporary bridge rules** under `#talos-faq:not(:has(.tfq-cols))` in `talos.css`.
+3. ProductLine "What can X do?" ask buttons + `useTalosSweep` (a version exists in `OurPlatform/viewModel/`).
 4. Re-sync `talosSparksRoute.ts` — the sparks line loops wrong around the moved Voice section.
-5. `TalosOrbLauncher` / `talos-orb.js` replacing the FAB on `/talos`, `.tfab-label`, TalosGuide bubbles, chat API `open(q, {expanded})` / `close()`.
 
 Design's `HeroWeave` / `HeroDots` / old Hero are dead code — do not port.
 
-## Gotchas
-
-- Design `body{background:transparent}` collapses onto `.talosPage` and wipes the page colour — drop the body background when porting.
-- `.talosPage` needs `isolation: isolate` so negative/low `z-index` backdrop layers paint above its background (it stands in for `<html>`).
-- Site-global `src/styles/index.css` sets `word-spacing: 0.08em` on `p`, `h2`–`h6`, `a`, `li`, `button` — changes line breaks vs the design. Reset to `normal` inside the page.
-- Tailwind preflight is global and can differ from the design's browser defaults — check margins/list/button resets when a section looks off.
-
 ## Change history
+- 2026-10-15 — Footer, launcher, Reveal, TalosMark, FAQ accordion, useRootStyles moved to shared components (no behaviour change); generic port rules moved to designer-prototype-port.md (TRUE-82652, tcox)
 - 2026-10-12 — Reduced-motion: no smooth scroll on `<html>`, instant subnav jumps; listed open placeholder copy/CTAs (TRUE-82042, tcox)
-- 2026-10-05 — Design drop 2, batches 1–2: talos.css regen (+`--ease-enter`, `.talos-mark`), Hero "Ask Talos", Voice → `.tproof-*`, FAQ bridge rules, useFitGap prerender skip (tcox)
+- 2026-10-05 — Design drop 2, batches 1–2: talos.css regen (+`--ease-enter`, `.talos-mark`), Hero "Ask Talos", Voice → `.tproof-*`, FAQ bridge rules, useFitGap prerender skip, orb launcher (tcox)
 - 2026-09-25 — Built /talos from the designer prototype; added Outlet context `openTalosChat`, `ROUTES_WITH_OWN_FOOTER`, TalosFab now opens chat (tcox)

package/knowledge/standalone/apps/togatech/workflows/designer-prototype-port.md

@@ -0,0 +1,57 @@
+---
+title: Porting a Designer Prototype to a togatech Page
+framework: "standalone"
+repo: togatech
+project: TOGA Technology Website
+client: shared
+type: workflow
+status: active
+updated: 2026-10-15
+owners: ["tcox"]
+files:
+  - togatech/src/utils/hooks/useRootStyles.ts
+  - togatech/src/utils/isPrerender.ts
+  - togatech/src/utils/isPinnedSceneLocked.ts
+  - togatech/src/components/TalosLauncher/view/TalosLauncher.tsx
+  - togatech/src/components/FooterV2/FooterV2.tsx
+  - togatech/src/components/SiteFaq/SiteFaq.tsx
+  - togatech/src/components/Reveal/Reveal.tsx
+  - togatech/src/components/templates/AppLayout/AppLayout.tsx
+related:
+  - ../architecture.md
+  - ../features/talos-product-page.md
+  - ../features/platform-product-page.md
+  - ../features/seo-aeo-geo-prerender.md
+  - ../features/navv2-global-nav.md
+  - local-dev-and-headless-verification.md
+---
+
+togatech procedure for turning a designer HTML/JSX/CSS prototype into a live page (`/talos`, `/our-platform`): where drops and port tools live, generated prefixed CSS, page root as `<html>`, design JS → hooks, shared page pieces, headless compare. Open before porting or re-porting a design drop.
+
+## Summary
+
+The designer ships static HTML + in-browser JSX + CSS prototypes. Each redesigned page is a port of one (`/talos` → [talos-product-page.md](../features/talos-product-page.md), `/our-platform` → [platform-product-page.md](../features/platform-product-page.md)). The method below is shared; page-specific rules live in each page doc.
+
+## Steps
+
+1. **Get the drop.** Drops live in `togatech/design-files/` — local only, excluded via `.git/info/exclude`, never committed. Current prototype: `design-files/uploads/New TOGA WEBSITE/TOGA Website/`. Port tools live in `design-files/_port-tools/` (also local only): `build-<page>-css.cjs`, `design-server.cjs` (serves the design on `localhost:8765`), `compare.cjs` (design vs port screenshots side by side), `hydration-check.cjs` (serves `dist/`, reports hydration errors per prerendered route), `perf.cjs`, `text-diff.cjs`. If a tool is lost, re-create it before the next design change.
+2. **Generate the page CSS — never hand-port it.** A postcss script concatenates the design CSS files **in the HTML's load order** into one plain file (`talos.css`, `ourPlatform.css`), prefixes every selector with the page root class (`.talosPage`, `.platformPage`), maps `:root` / `html` / `body` onto the root, rewrites asset urls to `/assets/<page>/`, keeps keyframe names. Port fixes go in the script's `EDITS` list (each asserts its exact match count, so a new drop that moves the text fails loudly) or its appended "port additions". Regenerate; never bulk hand-edit the output.
+   - Plain CSS, **not a CSS module**: design JS finds elements by raw class names/ids and sets keyframe names inline; hashing breaks that (CTO-reviewed).
+3. **Make the page root stand in for `<html>`.** Whatever the design writes on `document.documentElement` (attributes, custom properties) goes on the page root, since the CSS maps `html` there. Viewport reads stay on `documentElement`. Render constant root vars in JSX `style` (prerender-safe). The root needs `isolation: isolate` so low/negative `z-index` backdrop layers paint above its background.
+   - Real `<html>` styles (`overflow-x: clip` — never `hidden`, it breaks `position: sticky`; `scroll-behavior: smooth`) go through `useRootStyles(MODULE_CONST)`: layout effect, skips smooth scroll under `prefers-reduced-motion`, and **removes** the properties on unmount (never "restores" — a prerendered snapshot already carries them).
+4. **Port design scripts as viewModel hooks.** Custom elements and WebGL/canvas widgets become hooks on an empty React host (`dangerouslySetInnerHTML={{__html:""}}`) — never append into React-owned nodes (see [seo-aeo-geo-prerender.md](../features/seo-aeo-geo-prerender.md)). Engines skip under `isPrerender()` and pause off-screen and on a hidden tab. Keep the design's timing backstops (IntersectionObserver + rect polls, `setTimeout` retry chains) — rAF / ResizeObserver can go silent on cold load.
+5. **Reuse the shared page pieces — do not re-port them:** `components/FooterV2`, `components/TalosLauncher` (orb + guide bubbles; props `fields`, `liftObstacles`, optional `leftHero` / `waitForPins`; guide memory is per page, keyed by section ids; greeting optional; orb/guide CSS comes from the page's own generated CSS), `components/SiteFaq` (+ `useFaqAccordion`), `components/Reveal`, `components/TalosMark`, `utils/hooks/useBtnSpot`. Add the route to AppLayout `ROUTES_WITH_OWN_FOOTER` / `ROUTES_WITH_OWN_LAUNCHER`. Give every pinned scene `data-nav-pinned` ([navv2-global-nav.md](../features/navv2-global-nav.md)).
+6. **Wire the route** as a code-split prerendered route — checklist in [seo-aeo-geo-prerender.md](../features/seo-aeo-geo-prerender.md).
+7. **Map design links** (`*.html`) to real routes; an anchor the target page lacks falls back to the route (NavV2 Gotchas).
+8. **Compare against the design headlessly** (`compare.cjs`), then `hydration-check.cjs` on a prod build.
+
+## Gotchas
+
+- **Screenshot width is 12px off.** Puppeteer hides scrollbars, but the site's `html { scrollbar-gutter: stable }` still reserves 12px, so the port renders 12px narrower than the design. Compare at port width = design width + 12, or launch with `ignoreDefaultArgs: ['--hide-scrollbars']`. Real phones use overlay scrollbars — not a bug there.
+- **Design pages load React/Babel from a CDN** and render in the browser — wait for a rendered element, not only `networkidle`.
+- Design `body { background: transparent }` collapses onto the page root and wipes the page colour — drop it.
+- Site-global `src/styles/index.css` sets `word-spacing: 0.08em` on `p`, `h2`–`h6`, `a`, `li`, `button` — changes line breaks vs the design. Reset to `normal` inside the page.
+- Tailwind preflight is global and differs from browser defaults — check margins, lists and button resets when a section looks off.
+
+## Change history
+- 2026-10-15 — Created from the /talos and /our-platform ports: drop + tool locations, EDITS asserts, page root as `<html>`, shared pieces, 12px screenshot offset (TRUE-82652, tcox)

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

@@ -6,7 +6,7 @@ project: TOGA Technology Website
 client: shared
 type: workflow
 status: active
-updated: 2026-10-12
+updated: 2026-10-15
 owners: ["tcox"]
 files:
   - togatech/package.json
@@ -17,6 +17,7 @@ files:
 related:
   - ../architecture.md
   - ../features/careers-paylocity-job-openings.md
+  - designer-prototype-port.md
 ---
 
 Get togatech running on a dev machine and verify a data-driven section without Cypress — `npm install` first, `lint` is dead, Cypress 15 fails on Windows. Open before local verification.
@@ -41,6 +42,8 @@ The gotcha-avoidance path for getting `togatech` up on a dev machine and actuall
 - `robotsPlugin` hardcodes `./dist`: a `--outDir <other>` scratch build still writes `dist/robots.txt`, and its `closeBundle` errors if `dist/` does not exist. Harmless for scratch builds.
 - A production `vite build` sends GA4 hits even when served from localhost — headless checks against a prod build log real `localhost/...` page views. Verify against `npm run dev` where you can.
 - Watching the network tab is not proof a fetch is broken: see step 3 (persisted query cache).
+- **Git Bash rewrites route arguments.** A script arg like `/our-platform` becomes a Windows path (`C:/Program Files/Git/our-platform`). Prefix the command with `MSYS_NO_PATHCONV=1`.
+- Comparing screenshots against a design page: see [designer-prototype-port.md](designer-prototype-port.md) Gotchas (12px scrollbar-gutter offset, CDN-rendered design pages).
 
 ## Related
 
@@ -48,6 +51,7 @@ The gotcha-avoidance path for getting `togatech` up on a dev machine and actuall
 - [Careers Section — Live Paylocity Job Openings](../features/careers-paylocity-job-openings.md)
 
 ## Change history
+- 2026-10-15 — Git Bash route-arg path conversion (`MSYS_NO_PATHCONV=1`); link to design-compare gotchas (TRUE-82652, tcox)
 - 2026-10-12 — Root tsconfig checks nothing (build's `tsc` does not type-check); 13 known errors (tcox)
 - 2026-10-05 — Prod build sends GA hits from localhost; robotsPlugin closeBundle fails without dist/ (tcox)
 - 2026-09-25 — No eslint config either; `tsc -p tsconfig.app.json` path-filter tip; robotsPlugin ignores --outDir (tcox)

package/package.json

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