toga-ai 1.0.341 → 1.0.343

package/knowledge/2.0/apps/api2/features/surface-meta-option.md

@@ -6,8 +6,8 @@ project: API
 client: shared
 type: feature
 status: active
-updated: 2026-06-30
-owners: [jcardinal]
+updated: 2026-07-15
+owners: [jcardinal, apeterson]
 files:
   - api2/Component/Api/V2/V2.php
   - _underscore/Model/Core/Surface.php
@@ -61,7 +61,27 @@ traffic), behavior is **byte-for-byte unchanged** — pure data, zero extra work
   `Client.AclRecordScripts` dispatch grant — it 403'd EZ-1 on dev-sandbox until granted, exactly like
   `meta` did. See [surface-resolver](../../_underscore/features/surface-resolver.md).
 
+- **The tell that it's the dispatch-grant gate (not record-level READ) failing: the 403 EZ-1
+  response carries `identifiers.script` set to the script route** (e.g. `"meta"`). If you see
+  `identifiers.script`, chase `AclRecordScripts`, not `AclRecordPermissions`.
+- **Which roles the dispatch check reads depends on the record's `aclDatabase`.** The `surfaces`
+  Record has `aclDatabase = CORE`, so `getRecordScriptPhpMethod` matches the caller's **CORE** roles
+  (`Core.Roles`: 1=Public, 2=Integrations, 3=Super User, 4=Base) against the `AclRecordScripts` rows —
+  even though those rows physically live in each **client** DB. The public login surface authenticates
+  as CORE Public(1). (⚠ This corrects the earlier "keyed on client roles" note in
+  [surface-resolver](../../_underscore/features/surface-resolver.md) — the two disagree; confirm
+  against `V2.php getRecordScriptPhpMethod` before relying on either.)
+- **Seed the dispatch grants in EVERY client DB.** Grant pattern: `meta` + `meta-group` →
+  Public(1)/Super User(3)/Base(4); `debug` → Super User(3) only. A client DB missing the grant 403s
+  that tenant even though the code and Core metadata are identical — new/pre-existing client DBs
+  silently lack it.
+
 ## Change history
+- 2026-07-15 — Documented the diagnostic tell (`identifiers.script` present on the 403 EZ-1 → it is
+  the `AclRecordScripts` dispatch gate, not record READ); clarified the dispatch check reads the
+  caller's **CORE** roles because `surfaces.aclDatabase = CORE` (contradicts the earlier "client
+  roles" note — flagged for reconciliation); and that the per-role grants (`meta`/`meta-group` →
+  1/3/4, `debug` → 3 only) must be seeded in every client DB. (apeterson)
 - 2026-06-30 — Noted the grouped `meta-group` endpoint (batched multi-slug resolve) and that it needs
   its own per-role `AclRecordScripts` dispatch grant (403 EZ-1 until granted). (jcardinal)
 - 2026-06-29 — Documented the second ACL layer: scripted-API dispatch is authorized via

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

@@ -3,5 +3,5 @@
 | Doc | Summary | Files |
 |-----|---------|-------|
 | [TOGa Supply (toga2-supply) Architecture](architecture.md) | `toga2-supply` is the **React + Vite frontend** for TOGa Supply — warehouse fulfillment tooling (shipment selection, fulfill & ship against carrier APIs, NetSui | toga2-supply/src/api/toga.ts, toga2-supply/src/pages/ShipmentItems/view/ShipmentItemsPage.tsx, toga2-supply/src/pages/EditShipment/view/EditShipmentPage.tsx, toga2-supply/src/pages/EditShipment/api/UpdateShipmentApi.ts, toga2-supply/src/pages/Shipments/view/components/ShipmentsCardTableForm/ShipmentsCardTableForm.tsx |
-| [Fulfill & Ship](features/fulfill-and-ship.md) | Fulfill & Ship lets a warehouse user select sales-order line items, enter serials, pick a carrier/method, and in one action: create the Item Fulfillment records | toga2-supply/src/pages/ShipmentItems/view/ShipmentItemsPage.tsx, toga2-supply/src/pages/EditShipment/view/EditShipmentPage.tsx, toga2-supply/src/pages/EditShipment/view/components/forms/EditShipmentForm.tsx, toga2-supply/src/pages/EditShipment/view/components/SelectedShipmentItemsTable.tsx, toga2-supply/src/pages/EditShipment/view/helpers/ShipmentDetailsForm/renderEditShipmentFormInput.tsx, toga2-supply/src/pages/EditShipment/viewModel/FIELDS/DUMMYUPDATESHIPMENTFIELDS.json, toga2-supply/src/pages/EditShipment/view/modals/ReturnShippingModal.tsx, toga2-supply/src/components/ui/BaseInput/BaseInput.tsx, toga2-supply/src/pages/EditShipment/api/UpdateShipmentApi.ts, toga2-supply/src/pages/EditShipment/helpers/ShipmentDetailsForm/formatShipmentData.ts, toga2-supply/src/pages/EditShipment/types.ts, toga2-supply/src/pages/Shipments/view/ShipmentsPage.tsx, toga2-supply/src/pages/Shipments/view/components/ShipmentsCardTableForm/ShipmentsCardTableForm.tsx, toga2-supply/src/pages/Shipments/api/ShipmentsApi.ts, toga2-supply/src/pages/Shipments/types.ts, toga2-supply/src/pages/FulfilledShipments/view/FulfilledShipmentsPage.tsx, toga2-supply/src/components/ui/CardTable/CardTable.tsx, toga2-supply/src/components/ui/CardTable/types.ts, toga2-supply/src/assets/pen-line.svg, _underscore/Model/Client/ItemFulfillment.php, _underscore/Trait/Netsuite/ItemFulfillment.php, _underscore/Component/Library/Carriers/Ups/Ups.php |
+| [Fulfill & Ship](features/fulfill-and-ship.md) | Fulfill & Ship lets a warehouse user select sales-order line items, enter serials, pick a carrier/method, and in one action: create the Item Fulfillment records | toga2-supply/src/pages/ShipmentItems/view/ShipmentItemsPage.tsx, toga2-supply/src/pages/EditShipment/view/EditShipmentPage.tsx, toga2-supply/src/pages/EditShipment/view/components/forms/EditShipmentForm.tsx, toga2-supply/src/pages/EditShipment/view/components/SelectedShipmentItemsTable.tsx, toga2-supply/src/pages/EditShipment/view/helpers/ShipmentDetailsForm/renderEditShipmentFormInput.tsx, toga2-supply/src/pages/EditShipment/viewModel/FIELDS/DUMMYUPDATESHIPMENTFIELDS.json, toga2-supply/src/pages/EditShipment/helpers/ShipmentDetailsForm/renderEditShipmentFormInput.tsx, toga2-supply/tailwind.config.cjs, toga2-supply/src/pages/EditShipment/view/modals/ReturnShippingModal.tsx, toga2-supply/src/components/ui/BaseInput/BaseInput.tsx, toga2-supply/src/pages/EditShipment/api/UpdateShipmentApi.ts, toga2-supply/src/pages/EditShipment/helpers/ShipmentDetailsForm/formatShipmentData.ts, toga2-supply/src/pages/EditShipment/types.ts, toga2-supply/src/pages/Shipments/view/ShipmentsPage.tsx, toga2-supply/src/pages/Shipments/view/components/ShipmentsCardTableForm/ShipmentsCardTableForm.tsx, toga2-supply/src/pages/Shipments/api/ShipmentsApi.ts, toga2-supply/src/pages/Shipments/types.ts, toga2-supply/src/pages/FulfilledShipments/view/FulfilledShipmentsPage.tsx, toga2-supply/src/components/ui/CardTable/CardTable.tsx, toga2-supply/src/components/ui/CardTable/types.ts, toga2-supply/src/assets/pen-line.svg, _underscore/Model/Client/ItemFulfillment.php, _underscore/Trait/Netsuite/ItemFulfillment.php, _underscore/Component/Library/Carriers/Ups/Ups.php |
 | [AWS Amplify Build & Deploy (non-prod environments)](workflows/amplify-build-and-deploy.md) | How `toga2-supply` (React + Vite) builds and deploys on **AWS Amplify**. | toga2-supply/amplify.yml, toga2-supply/.gitattributes, toga2-supply/.github/workflows/sync-stage-environments.yml, toga2-supply/.env.qc-security |

package/knowledge/2.0/apps/toga2-supply/features/fulfill-and-ship.md

@@ -6,7 +6,7 @@ project: TOGa Supply
 client: shared
 type: feature
 status: active
-updated: 2026-07-14
+updated: 2026-07-15
 owners: [mhammontree]
 files:
   - toga2-supply/src/pages/ShipmentItems/view/ShipmentItemsPage.tsx
@@ -15,6 +15,8 @@ files:
   - toga2-supply/src/pages/EditShipment/view/components/SelectedShipmentItemsTable.tsx
   - toga2-supply/src/pages/EditShipment/view/helpers/ShipmentDetailsForm/renderEditShipmentFormInput.tsx
   - toga2-supply/src/pages/EditShipment/viewModel/FIELDS/DUMMYUPDATESHIPMENTFIELDS.json
+  - toga2-supply/src/pages/EditShipment/helpers/ShipmentDetailsForm/renderEditShipmentFormInput.tsx
+  - toga2-supply/tailwind.config.cjs
   - toga2-supply/src/pages/EditShipment/view/modals/ReturnShippingModal.tsx
   - toga2-supply/src/components/ui/BaseInput/BaseInput.tsx
   - toga2-supply/src/pages/EditShipment/api/UpdateShipmentApi.ts
@@ -102,6 +104,19 @@ layout, labels, required-ness, or ordering, edit the **config JSON**, not the co
 **Every react-select field's form value is the whole option OBJECT `{uuid, name}`, never a
 bare string** — see the gotcha below before wiring a new select field.
 
+- **Renderer extension points (how to add a non-BaseInput control).** `renderEditShipmentFormInput.tsx`
+  special-cases fields by boolean flags on the JSON field object (existing: `isClearAll`, `isReadOnly`;
+  added `isUnitSelector` = a native in./cm `<select>`, mirroring the Return Shipping modal — visual-only,
+  not persisted). **Reuse pattern for any custom control: add a flag to the JSON field + a branch in the
+  renderer** rather than forcing it through `BaseInput`. A per-section `sectionTitleContainerClasses` is
+  also read by `EditShipmentForm.tsx`'s shared section-title wrapper (default unchanged) so a section can
+  e.g. right-align its title (used to right-align the Item Count column's title + value to a shared edge).
+- **⚠ A custom/non-data field MUST set `valueKey: ""`.** Before rendering, `EditShipmentForm.tsx` runs
+  **every** field through `getValueFromPath(data, field.valueKey)`, which does `valueKey.split(".")` with
+  **no guard** — a field with no `valueKey` **white-screens the whole form** (`Cannot read properties of
+  undefined (reading 'split')`). Set `valueKey: ""` (same convention Clear All / Address already use) for
+  any field not bound to data.
+
 - **Create vs Edit are distinct entry points (decision — kept, not merged).** Select Items →
   Next = create a **New Shipment**; the pending-shipments pencil = **edit** an existing draft.
   They are deliberately NOT merged and there is no auto-load from Select Items, because a Sales
@@ -180,6 +195,19 @@ the call 403s and returns no label.
 
 ## Gotchas / known issues
 
+- **⚠ Tailwind does NOT scan the field-config JSON — a class used ONLY in `viewModel/FIELDS/*.json`
+  is silently inert.** The config-driven forms author Tailwind utility classes inside the field JSON
+  (e.g. `DUMMYUPDATESHIPMENTFIELDS.json`), but `tailwind.config.cjs` `content` globs only scan
+  `./src/**/*.{js,ts,jsx,tsx}` (+ `index.html` + toga-blox dist) — **not `.json`**. So a class used
+  *only* in the JSON never has its CSS rule generated: it appears in the DOM `className` but does
+  nothing. Common classes (`gap-1`, `w-4`, `w-full`) happen to also appear in `.tsx` so they compile;
+  unusual JSON-only classes do not. *Concrete failure:* `!w-fit` (keep the "Needs a return label"
+  checkbox content-width so the Edit link stays beside it) was JSON-only → never generated → `w-full`
+  won → the checkbox stretched with the column and the Edit gap grew on wide screens (col1 is `w-56`
+  above 1893px, `w-150px` below), fine only when narrow. **Fix applied (surgical):** added
+  `safelist: ["!w-fit"]` to `tailwind.config.cjs`. **Recommended clean fix (NOT yet done):** add the
+  FIELDS JSON to the `content` globs (e.g. `"./src/**/FIELDS/*.json"`) and re-test all config-driven
+  forms, since any JSON-only class is otherwise inert.
 - **UPS test endpoint** (`wwwcie.ups.com`, debug mode) returns a constant tracking
   number `1ZXXXXXXXXXXXXXXXX` + SAMPLE labels. On 2nd+ test runs this collides with the
   `TrackingNumbers.number` UNIQUE index (surfaces mislabeled as "Labelary API error")
@@ -345,6 +373,15 @@ not the base `_Model_Client_ItemFulfillment`. Tested with GroWrk; UPS support wa
 for Compass and is not yet in prod.
 
 ## Change history
+- 2026-07-15 — TRUE-79191 (Figma-alignment polish pass): documented two durable items on the
+  config-driven form — (1) **Tailwind does not scan `viewModel/FIELDS/*.json`**, so a JSON-only utility
+  class is silently inert (`!w-fit` footgun; surgical `safelist` fix, recommended clean fix = add the
+  JSON to `content` globs); (2) **renderer extension points** — the `isUnitSelector` custom-control
+  branch + the flag-in-JSON/branch-in-renderer pattern, per-section `sectionTitleContainerClasses`, and
+  the **`valueKey: ""` requirement** for any custom/non-data field (empty/absent `valueKey` white-screens
+  the form via `getValueFromPath`'s unguarded `.split`). Remaining Figma tweaks (Dimensions in./cm
+  dropdown + gaps, Item Count right-align, return-label row gaps, shipment-card indicator top gap) were
+  cosmetic — no doc change. (mhammontree)
 - 2026-07-14 — TRUE-79191 (commit `724d17c1a`): fixed **Signature Type** not saving/rehydrating —
   documented the reusable **whole-object react-select** convention (`{uuid,name}`; map on `.uuid`,
   rehydrate the object) as a gotcha; the string comparison `data.signatureType === "Required"`

package/package.json

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