toga-ai 1.0.147 → 1.0.149

package/knowledge/2.0/apps/_underscore/features/recursive-item-fulfillments.md

@@ -6,8 +6,8 @@ project: _Underscore
 client: shared
 type: feature
 status: active
-updated: 2026-06-08
-owners: [jcardinal]
+updated: 2026-06-19
+owners: [jcardinal, rgirish]
 files:
   - _underscore/Model/Client/ItemFulfillment.php
   - _underscore/Model/Client/ItemFulfillmentItem.php
@@ -101,15 +101,18 @@ inheritance. Verified against prod `Client_Compass` chains (≥3 levels deep).
   post-delete hooks never fire; a standalone downstream DELETE doesn't immediately remove its
   upstream mirror. A later reconciling PUT cleans up stale records via set comparison. Full
   delete handling would need a `preDelete` mechanism + `PRE/DELETE` interceptor rows.
+- **Transfer-order fulfillments are explicitly excluded from the upstream walk.** `reconcileUpstreamLevel()` returns `null` immediately when the downstream IF has `transferOrderId` set (no `salesOrderId`). This is intentional for standalone TOs (GroWrk v1). When SO→TO→SO chain scenarios are needed, Phase 5 of the GroWrk transfer order plan extends this method to walk `TransferOrders_SalesOrders` bridge tables — see `clients/growrk/features/transfer-order-flow.md`.
 - **Out of scope:** NetSuite sync of upstream IFs; transfer-order fulfillments
   (`transferOrderId`) are skipped.
 - **Performance:** every child write re-runs a full upstream walk (read-heavy, but each
   upstream record is written at most once — idempotent). Fine for normal fulfillment sizes.
 
 ## Change history
+- 2026-06-19 — Documented explicit TO exclusion in reconcileUpstreamLevel; cross-linked GroWrk transfer order plan. (rgirish)
 - 2026-06-08 — Documented the Recursive Item Fulfillments engine (interceptor-driven upstream fulfillment mirroring, bundle scaling, reconcile loop). (jcardinal)
 
 ## Related docs
+- GroWrk transfer order flow plan: `clients/growrk/features/transfer-order-flow.md`.
 - `_underscore` architecture (interceptors, `internalApiRequest`, `_Model` layer).
 - `api2` architecture (V2 metadata engine that fires these interceptors; the
   commit-logs / rollback-data-on-failure transaction invariant the throws rely on).

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/INDEX.md

@@ -14,7 +14,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 
 ## 2.0 framework
 
-- **_underscore** (_Underscore) _(framework core)_ — 8 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
+- **_underscore** (_Underscore) _(framework core)_ — 9 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
 - **worker2** (Worker) — 8 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
 - **api2** (API) — 4 doc(s) → [2.0/apps/api2/INDEX.md](2.0/apps/api2/INDEX.md)
 - **dbchanges2** (Database Changes) _(framework core)_ — 1 doc(s) → [2.0/apps/dbchanges2/INDEX.md](2.0/apps/dbchanges2/INDEX.md)
@@ -38,6 +38,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 - **Compass Canada** (`compass-canada`) → [clients/compass-canada/INDEX.md](clients/compass-canada/INDEX.md)
 - **Compass USA** (`compass-usa`) → [clients/compass-usa/INDEX.md](clients/compass-usa/INDEX.md)
 - **Elite** (`elite`) → [clients/elite/INDEX.md](clients/elite/INDEX.md)
+- **GroWrk** (`growrk`) → [clients/growrk/INDEX.md](clients/growrk/INDEX.md)
 - **New York City Department of Education** (`nycdoe`) → [clients/nycdoe/INDEX.md](clients/nycdoe/INDEX.md)
 - **Office Depot** (`office-depot`) → [clients/office-depot/INDEX.md](clients/office-depot/INDEX.md)
 - **Prudential Financial** (`prudential`) → [clients/prudential/INDEX.md](clients/prudential/INDEX.md)

package/knowledge/clients/growrk/INDEX.md

@@ -0,0 +1,6 @@
+# Client: GroWrk `growrk`
+
+| Doc | Framework | Summary | Files |
+|-----|-----------|---------|-------|
+| [Transfer Order Flow (NetSuite SalesOrder workaround → dedicated TransferOrders)](features/transfer-order-flow.md) | 2.0 | GroWrk moves inventory between their own locations (warehouses, distribution points). | _underscore/Model/Client/TransferOrder.php, _underscore/Model/Client/TransferOrderItem.php, _underscore/Model/Client/ItemFulfillment.php, _underscore/Model/Client/ItemReceipt.php, _underscore/Model/Client/ItemReceiptItem.php, _underscore/Trait/Netsuite/TransferOrder.php, dbchanges2/Client_Growrk/, dbchanges2/Client/ |
+| [GroWrk](profile.md) | 2.0 | GroWrk is a 2.0 client using TOGA for inventory and order management. |  |

package/knowledge/clients/growrk/features/transfer-order-flow.md

@@ -0,0 +1,119 @@
+---
+title: "Transfer Order Flow (NetSuite SalesOrder workaround → dedicated TransferOrders)"
+framework: "2.0"
+repo: _underscore
+project: _Underscore
+client: growrk
+type: client-feature
+status: active
+updated: 2026-06-19
+owners: ["rgirish"]
+files:
+  - _underscore/Model/Client/TransferOrder.php
+  - _underscore/Model/Client/TransferOrderItem.php
+  - _underscore/Model/Client/ItemFulfillment.php
+  - _underscore/Model/Client/ItemReceipt.php
+  - _underscore/Model/Client/ItemReceiptItem.php
+  - _underscore/Trait/Netsuite/TransferOrder.php
+  - dbchanges2/Client_Growrk/
+  - dbchanges2/Client/
+related:
+  - 2.0/apps/_underscore/features/recursive-item-fulfillments.md
+  - 2.0/apps/worker2/architecture.md
+---
+
+## Summary
+
+GroWrk moves inventory between their own locations (warehouses, distribution points). Historically this was done by creating zero-dollar SalesOrders with `holdInvoice=true` in NetSuite — polluting sales reporting, distorting demand planning, and creating audit confusion. This feature introduces a dedicated `TransferOrders` record type in the TOGA database. NetSuite continues to receive transfer orders as SalesOrders with `holdInvoice=true` (no NS-side change); the distinction is made and stored only on the TOGA side.
+
+## Key files / entry points
+
+| File | Role |
+|---|---|
+| `_underscore/Model/Client/TransferOrder.php` | TO model — origin/destination locations, number, serviceRequestId, purchaseOrderId, c_netsuiteInternalSalesOrderId |
+| `_underscore/Model/Client/TransferOrderItem.php` | TO line items — itemId, quantity, lineNumber |
+| `_underscore/Trait/Netsuite/TransferOrder.php` | NS sync trait — **currently a stub** (only declares c_netsuiteInternalSalesOrderId); `syncNetsuiteTransferOrder()` not yet implemented |
+| `_underscore/Model/Client/ItemFulfillment.php` | Outbound closure — `transferOrderId` FK already present; `salesOrderId` must be made nullable |
+| `_underscore/Model/Client/ItemReceipt.php` | Inbound closure — `transferOrderId` FK already present |
+| `dbchanges2/Client_Growrk/` | Client-specific schema fixes (dtCreated/dtUpdated/isActive on TransferOrders, nullable XOR columns) |
+| `dbchanges2/Client/` | All-client bridge tables (8 new SO↔TO and PO↔TO bridge tables) |
+
+## How it works
+
+### Identification signal
+A NetSuite SalesOrder is a TransferOrder if and only if: `holdInvoice === true` AND `total === 0`. Both conditions must hold — `holdInvoice` alone is not sufficient.
+
+### Two-stage closure
+- **Outbound:** An `ItemFulfillment` with `transferOrderId` set (not `salesOrderId`) closes the outbound side — items leave the origin location.
+- **Inbound:** An `ItemReceipt` with `transferOrderId` set (not `purchaseOrderId`) closes the inbound side — items arrive at the destination location.
+
+### Chain positions
+Transfer orders can sit in several positions in the order chain:
+1. **Standalone TO** — pure location-to-location move, no SO/PO involved
+2. **SO → TO** — customer SO triggers an internal TO (outbound from origin)
+3. **PO → TO** — vendor PO received via TO (move to warehouse)
+4. **SO → TO → SO** — customer-facing SO, internal move, downstream SO to fulfill
+
+## Data model
+
+### TransferOrders (prod — `Client_Growrk`)
+| Column | Type | Notes |
+|---|---|---|
+| id | int PK | |
+| uuid | char(36) | |
+| originLocationId | int FK | NOT NULL |
+| destinationLocationId | int FK | NOT NULL |
+| dateOrder | date | nullable |
+| number | varchar | currently varchar — generate as `TO-<tranId>` from NS in sync trait |
+| serviceRequestId | int FK | nullable |
+| purchaseOrderId | int FK | nullable |
+| customerIdentificationNumber | varchar | nullable |
+| c_netsuiteInternalSalesOrderId | varchar | NS SalesOrder internal ID |
+| **dtCreated** | datetime | **MISSING — must add in Phase 1** |
+| **dtUpdated** | datetime | **MISSING — must add in Phase 1** |
+| **isActive** | tinyint | **MISSING — must add in Phase 1** |
+
+### Columns that need schema fixes before first use
+- `ItemFulfillments.salesOrderId` — currently NOT NULL; must be made nullable (XOR with transferOrderId)
+- `ItemFulfillmentItems.salesOrderItemId` — currently NOT NULL; must be made nullable
+- `ItemReceiptItems.purchaseOrderItemId` — currently NOT NULL; must be made nullable (XOR with transferOrderItemId)
+
+### New bridge tables (all 8 in `dbchanges2/Client/` — applies to all clients)
+| Table | FK A | FK B |
+|---|---|---|
+| SalesOrders_TransferOrders | salesOrderId | transferOrderId |
+| TransferOrders_SalesOrders | transferOrderId | salesOrderId |
+| PurchaseOrders_TransferOrders | purchaseOrderId | transferOrderId |
+| TransferOrders_PurchaseOrders | transferOrderId | purchaseOrderId |
+| SalesOrderItems_TransferOrderItems | salesOrderItemId | transferOrderItemId |
+| TransferOrderItems_SalesOrderItems | transferOrderItemId | salesOrderItemId |
+| PurchaseOrderItems_TransferOrderItems | purchaseOrderItemId | transferOrderItemId |
+| TransferOrderItems_PurchaseOrderItems | transferOrderItemId | purchaseOrderItemId |
+
+`Core.Records` already has id=312 (`_Model_Client_TransferOrder`) and id=313 (`_Model_Client_TransferOrderItem`) registered.
+
+## Implementation plan (5 phases — team review pending)
+
+Full plan saved at `/Applications/AMPPS/www/transfer-order-plan.md`.
+
+| Phase | Work | Status |
+|---|---|---|
+| 1 | Schema fixes (dtCreated/dtUpdated/isActive, nullable XOR columns, 8 bridge tables, Core RecordFields) | Pending |
+| 2 | PHP model updates (TransferOrder.php fields, 8 bridge model stubs) | Pending |
+| 3 | _Trait_Netsuite_TransferOrder sync impl + ItemReceipt TO path | Pending |
+| 4 | worker2 _Worker_Netsuite_TransferOrder action class | Pending |
+| 5 | Upstream IF chain extension (SO→TO→SO walk) | Deferred |
+
+## Gotchas / known issues
+
+- **`dtCreated`/`dtUpdated` MISSING from `TransferOrders` in prod.** Any `_Model_Client_TransferOrder::save()` call will fail silently until Phase 1 runs. This is a hard blocker — nothing else works until the schema fix lands.
+- **XOR is application-layer only.** MySQL does not enforce that exactly one of `salesOrderId`/`transferOrderId` is set on `ItemFulfillments`. The sync trait and any POST interceptor must validate this explicitly.
+- **`_Trait_Netsuite_TransferOrder` is a stub.** It declares only `$c_netsuiteInternalSalesOrderId` — there is no `syncNetsuiteTransferOrder()` method yet.
+- **Upstream IF chain explicitly skips TOs today.** `ItemFulfillment::reconcileUpstreamLevel()` returns null when `transferOrderId` is set — the comment reads "no salesOrderId (transfer order) → return null (out of scope)". Phase 5 will extend this.
+- **Lazy transaction gotcha.** `_Database::register()` auto-starts a lazy transaction since Apr 2026. The worker must call `_Database::transactionCommit(DB_CLIENT)` before any SQS dispatch or the TO insert rolls back silently.
+- **Bridge table scope confirmed as all-clients.** The 8 bridge tables go in `dbchanges2/Client/` (not `Client_Growrk/`). Schema fixes (dtCreated etc.) stay in `Client_Growrk/` — other clients don't need them.
+- **NS identification: both conditions required.** `holdInvoice=true` alone is not a safe signal — must also confirm `total === 0`.
+
+## Change history
+
+- 2026-06-19 — Designed full transfer order flow; confirmed DB state in prod; produced 5-phase implementation plan pending team review (rgirish)

package/knowledge/clients/growrk/profile.md

@@ -0,0 +1,22 @@
+---
+title: "GroWrk"
+framework: "2.0"
+apps:
+  - _underscore
+  - api2
+  - worker2
+  - dbchanges2
+project: _Underscore
+client: growrk
+type: profile
+status: active
+updated: 2026-06-19
+owners: ["rgirish"]
+files: []
+related:
+  - clients/growrk/features/transfer-order-flow.md
+---
+
+## Summary
+
+GroWrk is a 2.0 client using TOGA for inventory and order management. Their primary integration involves inventory movements between locations (warehouses, distribution points). NetSuite is the ERP. The key engineering challenge is that GroWrk historically used zero-dollar SalesOrders with holdInvoice=true in NetSuite as a workaround to represent internal inventory transfers — work is underway to replace this with a dedicated TransferOrders record type in the TOGA DB while keeping NetSuite unchanged.

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.147",
+  "version": "1.0.149",
   "description": "TOGA Technology Team Claude Knowledge System — shared AI coding harness with skills, knowledge base CLI, and project installer for Claude Code.",
   "keywords": [
     "claude",