toga-ai 1.0.146 → 1.0.148

package/knowledge/CONVENTIONS.md

@@ -8,10 +8,13 @@
 
 ## The two axes
 
-1. **Framework first.** Everything app- or framework-related lives under `1.0/` or
-   `2.0/`. These are the two PHP frameworks:
-   - **1.0** — the `App_` framework; core repo **`library`**.
-   - **2.0** — the `_underscore` framework; core repo **`_underscore`**.
+1. **Framework first.** Everything app- or framework-related lives under `1.0/`,
+   `2.0/`, or `standalone/`:
+   - **1.0** — the `App_` PHP framework; core repo **`library`**.
+   - **2.0** — the `_underscore` PHP framework; core repo **`_underscore`**.
+   - **standalone** — apps that belong to **no** PHP framework (e.g. `togatech`, a React/TS
+     site; `forward`). They live under `standalone/apps/<repo>/`, have **no framework core**,
+     and depend on nothing implicitly. Not everything is 1.0 or 2.0.
 2. **Shared vs. client.** Within a framework, app/feature/architecture knowledge
    lives under `apps/<repo>/`. Anything specific to a single client lives at the top
    level under `clients/<client>/` and tags its `framework` in frontmatter.
@@ -29,6 +32,8 @@ knowledge/
 ├── 2.0/
 │   ├── apps/<repo>/architecture.md + features/*.md + workflows/*.md
 │   └── standards/*.md     # 2.0 coding standards (_underscore)
+├── standalone/
+│   └── apps/<repo>/architecture.md + features/*.md  # non-PHP apps (e.g. togatech); no core
 └── clients/<client>/
     ├── profile.md
     ├── features/*.md      # client-specific feature overrides (link back to apps/)
@@ -49,13 +54,14 @@ The shared identity/topology of every repo. Maintained **only by the skills**.
 
 - `repo` — on-disk repo/folder name (the key; unique).
 - `project` — logical project name.
-- `framework` — `"1.0"` or `"2.0"`.
+- `framework` — `"1.0"`, `"2.0"`, or `"standalone"` (non-PHP apps with no framework core).
 - `role` — `"core"` (the framework base every same-framework repo depends on) or `"app"`.
 - `dependsOn` — additional repos this one depends on beyond the framework core
   (e.g. `api2` may later depend on `apiproxy`).
 
 **Dependency loading:** every repo implicitly depends on its framework's `core` repo
-(`_underscore` for 2.0, `library` for 1.0), plus any transitive `dependsOn`.
+(`_underscore` for 2.0, `library` for 1.0), plus any transitive `dependsOn`. `standalone`
+apps have no framework core, so they load only themselves plus any explicit `dependsOn`.
 `node knowledge.js deps --repo=<repo>` resolves the full load order.
 
 ## Client app-scope (`apps:` on `profile.md`)

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

@@ -2,4 +2,5 @@
 
 | Doc | Framework | Summary | Files |
 |-----|-----------|---------|-------|
+| [Grand & Toy ASN Import (Compass Canada)](features/grand-and-toy-asn-import.md) | 2.0 | Imports Grand & Toy (G&T) Advance Shipping Notices for Compass Canada. | worker/crons/toga2/compasscanada/workflow/4_import_grand_and_toy_advance_shipping_notices.php, worker/crons/toga2/compasscanada/workflow/import_grand_and_toy_asn_from_file.php, worker/schedules/cron.worker.sync.json, _underscore/Model/Compass/AdvanceShippingNotice.php, _underscore/Model/Compass/Canada/AdvanceShippingNotice.php, dbchanges2/Client_CompassCanada/ |
 | [Compass Canada](profile.md) | 2.0 | Compass Canada is the Canadian arm of the Compass account — a separate TOGA tenant, related to but distinct from Compass USA. |  |

package/knowledge/clients/compass-canada/features/grand-and-toy-asn-import.md

@@ -0,0 +1,105 @@
+---
+title: Grand & Toy ASN Import (Compass Canada)
+framework: "2.0"
+project: _Underscore
+client: compass-canada
+type: client-feature
+status: active
+updated: 2026-06-19
+owners: ["bala"]
+files:
+  - worker/crons/toga2/compasscanada/workflow/4_import_grand_and_toy_advance_shipping_notices.php
+  - worker/crons/toga2/compasscanada/workflow/import_grand_and_toy_asn_from_file.php
+  - worker/schedules/cron.worker.sync.json
+  - _underscore/Model/Compass/AdvanceShippingNotice.php
+  - _underscore/Model/Compass/Canada/AdvanceShippingNotice.php
+  - dbchanges2/Client_CompassCanada/
+related:
+  - ../profile.md
+---
+
+## Summary
+Imports Grand & Toy (G&T) Advance Shipping Notices for Compass Canada. A 1.0 worker cron reads
+G&T's ASN CSV from a mailbox, posts each shipped line to the 2.0 API as an AdvanceShippingNotice
+(ASN); a Compass interceptor then auto-creates the ItemFulfillment chain, and the customer gets
+an in-transit email in English or French. It mirrors the Compass USA ODP / Strategic-Systems ASN
+flow, adapted for Canadian carriers and bilingual email.
+
+## Key files / entry points
+- `worker/crons/toga2/compasscanada/workflow/4_import_grand_and_toy_advance_shipping_notices.php`
+  — the scheduled cron (1.0 worker tier). Reads mailbox `compasscanada.status@togatech.com`
+  (OAuth2 creds in config `[compasscanada]`), parses the 24-column CSV, posts to api2
+  `/advance-shipping-notices`. Scheduled in `worker/schedules/cron.worker.sync.json` (every 4h).
+- `_underscore/Model/Compass/AdvanceShippingNotice.php` — `postPost` interceptor that builds the
+  ItemFulfillment chain on each ASN POST. Compass Canada inherits it via the empty
+  `_underscore/Model/Compass/Canada/AdvanceShippingNotice.php`.
+- `worker/crons/toga2/compasscanada/workflow/import_grand_and_toy_asn_from_file.php` — one-time
+  backfill variant: reads a CSV from disk (no mailbox/OAuth), creates ASN data only, sends NO
+  user emails/notifications, and stamps `c_dtInTransitEmailSent = NOW()`.
+
+## How it works
+1. Cron gets an O365 OAuth2 token (creds from `App_Registry::get('config')['compasscanada']`),
+   opens the INBOX.
+2. Per attachment: decode CSV, gate on exactly 24 columns (otherwise email the team the file +
+   skip).
+3. Per row: skip electronic-delivery carriers (`Digital` / `E-delivered` / `E-verified`);
+   validate PO / part / tracking; look up SO + contact user + CC addresses; resolve carrier →
+   Ground shipping method; upsert `TrackingNumbers`; resolve the item by
+   `VendorItems.vendorPartNumber`; find-or-create a `Units` row per serial.
+4. POST `/advance-shipping-notices` with the tracking number nested at header + item + unit
+   level (so the interceptor sees it during the POST).
+5. The Compass ASN `postPost` interceptor (when enabled) creates the `ItemFulfillment` (one per
+   SO number, reused if it exists), `ItemFulfillmentItems`, `ItemFulfillmentItemUnits`, and the
+   IF/IFI/IFIU `_TrackingNumbers` bridges.
+6. Only when a tracking number is newly inserted: write Notifications (1.0 `db_store` + 2.0),
+   resolve the user's language, send the EN/FR in-transit email via POST
+   `/email-templates/sendEmail`, then stamp `c_dtInTransitEmailSent = NOW()`.
+
+## Data model
+- ASN: `AdvanceShippingNotices` / `…Items` / `…ItemUnits` + their `…_TrackingNumbers` bridges.
+- IF: `ItemFulfillments` / `…Items` / `…ItemUnits` + their `…_TrackingNumbers` bridges.
+- Vendor: `App_Client_CompassCanada::UUID_VENDOR__GRAND_TOY`.
+- Carriers + methods: `ShippingCarriers` Precision / Purolator / ATSL / Nationex, each with its
+  own Ground `ShippingMethods` row (added 2026-06-18 via dbchanges2; tracking-URL prefixes +
+  carrier logos set on the carrier).
+- Language: `UserGlobalSettings.settingId = 2`, values `en` / `fr-CA`. In-transit `EmailTemplates`
+  uuids — EN `26d2cb67-bdc5-4973-9e39-160c89b0af56`, FR `fb8be211-7c07-4939-9682-08b6c3245f66`.
+- Interceptor wiring: `Core.RecordScripts` + `Core.ApiPayloadInterceptors`, `recordId 55`
+  (AdvanceShippingNotice). The `sendEmail` POST record script is `Core.RecordScripts recordId 202`.
+
+## Client variations
+Compass-Canada-specific; parallels Compass USA's ODP / Strategic-Systems ASN import. Canada sends
+a bilingual EN/FR in-transit email (USA is English only) and uses Canadian carriers.
+
+## Gotchas / known issues
+- **CSV "Part Number" is the VENDOR part number (`VendorItems.vendorPartNumber`), NOT
+  `Items.partNumber`.** Resolve the item through `VendorItems`. (e.g. vendor `IMFP3260` →
+  `Items.partNumber` `C2CY5UC#ABA`.)
+- **G&T's ASN file inconsistently drops the `IM` prefix** (`FP3260` vs `IMFP3260`) on some lines
+  → item-not-found → those lines are skipped and reported in the import-report email. This is a
+  G&T-side export issue; toga transmits the correct `IMFP…` to G&T as the cXML `SupplierPartID`
+  (see `2_transmit_mits_purchase_orders_to_vendors.php`), so it is NOT a MITS bug.
+- **The ASN→IF interceptor must be ENABLED per client.** `Core.ApiPayloadInterceptors` for
+  `recordId 55`, `prePostProcessing=POST`, `httpMethod=POST` must be `isActive=1` (and the client
+  `AclRecordScripts` must grant the caller's roles). It was OFF for Compass Canada; enabling it is
+  required or ASNs post but the IF/IFI/IFIU chain never builds.
+- **Tracking must be nested in the ASN POST payload** (header/item/unit), not linked via SQL
+  after the POST — the interceptor runs during the POST, so post-POST links are invisible to it.
+- **`/email-templates/sendEmail` must be POST** (not GET) so a large `orderItems` HTML payload
+  does not hit the URL-length limit (HTTP 414). POST requires the `sendEmail` record script
+  registered for the POST method (`Core.RecordScripts`), else the engine returns `EV-8`.
+- Each CSV line creates one ASN; the interceptor dedups to **one ItemFulfillment per SO**.
+- A new carrier needs its **own** Ground `ShippingMethod`, or the TrackingNumber ends up with the
+  right carrier but another carrier's Ground method id.
+- `App_Database::fetchOne()` (1.0) throws on a 0-row result — guard item lookups with `numRows()`
+  before `fetchOne()`.
+- The cron reads OAuth2 creds from config `[compasscanada]`; the updated `config.<env>.ini` must
+  be deployed with the code or the token request fails.
+
+## Change history
+- 2026-06-19 — Built the G&T ASN import cron + one-time backfill script; matched items by
+  `VendorItems.vendorPartNumber`; added Canadian carriers + per-carrier Ground methods; EN/FR
+  in-transit email via POST; enabled the Compass ASN→IF interceptor for Compass Canada. (bala)
+
+## Related docs
+- [Compass Canada profile](../profile.md)

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

@@ -12,7 +12,7 @@ project: _Underscore
 client: compass-canada
 type: profile
 status: active
-updated: 2026-06-18
+updated: 2026-06-19
 owners: [jcardinal, bala]
 files: []
 related:
@@ -31,10 +31,17 @@ to but distinct from Compass USA. Like Compass USA it spans the **2.0** commerce
 - **1.0:** worker crons under `worker/crons/toga2/compasscanada/`.
 
 ## Vendors & integrations
-- Not yet captured. Confirm vendors / ASN ingestion paths before relying on them.
+- **Grand & Toy (G&T)** — primary hardware vendor. SOs flow toga → MITS → PO to G&T; G&T sends
+  back ASNs. ASN ingestion (email CSV + the auto-created ItemFulfillment chain + bilingual
+  in-transit email) is documented in [Grand & Toy ASN Import](features/grand-and-toy-asn-import.md).
+  Vendor uuid: `App_Client_CompassCanada::UUID_VENDOR__GRAND_TOY`. Canadian carriers in use:
+  UPS, FedEx, Purolator, Precision, Nationex, ATSL (each with a Ground `ShippingMethod`).
+- Worker crons for the G&T flow live under `worker/crons/toga2/compasscanada/workflow/`
+  (`1_…` transmit SOs to MITS, `2_…` transmit POs to vendors, `3_…` status from G&T cXML,
+  `4_…` import G&T ASNs).
 
 ## Notes
-- **Stub** — created alongside the Compass USA profile for disambiguation. The 2026-06-08 ASN
-  → ItemFulfillment work was for **Compass USA**, not Compass Canada. Expand this profile as
-  Compass Canada behavior is investigated.
+- Customer language preference: `UserGlobalSettings.settingId = 2` (`en` / `fr-CA`); customer-
+  facing emails are sent in EN or FR accordingly.
+- The 2026-06-08 ASN → ItemFulfillment work was for **Compass USA**, not Compass Canada.
 - Related: [Compass USA](../compass-usa/profile.md).

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

@@ -6,8 +6,8 @@ project: TOGA Technology Website
 client: shared
 type: feature
 status: active
-updated: 2026-06-18
-owners: ["ajean"]
+updated: 2026-06-19
+owners: ["ajean", "jcardinal"]
 files:
   - togatech/vite.config.ts
   - togatech/scripts/prerender.mjs
@@ -24,7 +24,7 @@ related: []
 ---
 
 ## 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) — **not yet merged/deployed** as of 2026-06-18.
+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).
 
 ## Key files / entry points
 - `vite.config.ts` — `robotsPlugin()` now gates on **Vite `mode`** (was `NODE_ENV && VITE_ENV`).
@@ -35,7 +35,7 @@ Makes togatech.com visible and citable to search engines **and** AI answer engin
 
 ## How it works
 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 && 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**.
+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:** Organization + WebSite site-wide (AppLayout), per-page BreadcrumbList (Seo), platform SoftwareApplication (OurPlatform), LocalBusiness×5 (from Contact locations), Person (from About team) — all **derived from existing FIELDS** (single source).
 
@@ -48,7 +48,10 @@ None — uniform.
 ## Gotchas / known issues
 - **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.
-- **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. Puppeteer's Chrome must be installed at build time: `npx puppeteer browsers install chrome`.
+- **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.
 - **🔴 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).
@@ -56,6 +59,7 @@ None — uniform.
 - **Build size:** JS bundle is ~14.8 MB (4.9 MB gzip) — a real CWV/LCP risk; code-splitting is a separate follow-up.
 
 ## Change history
+- 2026-06-19 — Merged SEO/AEO into `_production` (resolved ContactPage conflict: reCAPTCHA + Seo/JsonLd, dropped Helmet). Fixed Amplify build: committed `package-lock.json` (npm ci EUSAGE) and added `npx puppeteer browsers install chrome` to the build before prerender. (jcardinal)
 - 2026-06-18 — Initial SEO/AEO/GEO implementation: robots mode-gate + AI allow-list + sitemap/llms; Puppeteer prerender (fail-fast); shared `<Seo>` single-source meta + canonical; JSON-LD (Organization/WebSite/Breadcrumb/SoftwareApplication/LocalBusiness×5/Person×12). PRs #29 + #30, pending merge. (ajean)
 
 ## Related docs

package/package.json

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