toga-ai 1.0.194 → 1.0.196

package/knowledge/2.0/apps/_underscore/INDEX.md

@@ -6,6 +6,8 @@
 | [ACL Permission Chain (Record & Field Authorization)](features/acl-permission-chain.md) | Authorization in the 2.0 API is **metadata-driven**: whether a role may Create/Read/Update/Delete a record is decided by rows across **four linked tables**, not | api2/Component/Api/V2/V2.php, _underscore/Model/Core/Page.php, dbchanges2/Client/2026-06-03- BLANK_CLIENT_DATABASE.sql, dbchanges2/Client/2026-06-23b - ItemTranslationsAcl.sql |
 | [Carrier Shipping Labels (UPS/FedEx) & NetSuite Item Fulfillment](features/carrier-shipping-labels.md) | Backend mechanics behind TOGa Supply's Fulfill & Ship: buying a carrier label (UPS/FedEx), persisting it, and creating the NetSuite Item Fulfillment with tracki | _underscore/Model/Client/ItemFulfillment.php, _underscore/Model/Client/ItemFulfillments/TrackingNumber.php, _underscore/Component/Library/LabelPdf/LabelPdf.php, _underscore/Component/Library/Carriers/Ups/Ups.php, _underscore/Component/Library/Carriers/Fedex/Fedex.php, _underscore/Trait/Netsuite/ItemFulfillment.php, _underscore/Trait/Netsuite/SalesOrder.php, _underscore/Component/Library/NetSuite/NetSuite.php, _underscore/Model/Client/TrackingNumber.php, _underscore/Model/Client/ShippingMethod.php, _underscore/Model.php, _underscore/Cloud.php |
 | [Client Email Template Sending](features/email-template-sending.md) | `_Model_Client_EmailTemplate` sends a stored, client-defined email template by UUID. | _underscore/Model/Client/EmailTemplate.php, _underscore/Model/Client/EmailTemplateOutgoingEmailAddress.php, _underscore/Email.php |
+| [Forecast.Sales NetSuite import engine (real-time webhook)](features/forecast-sale-import.md) | Real-time importer that takes a NetSuite **sale** record and writes its lines into `Forecast.Sales` (the Forecast2 revenue table). | _underscore/Component/Forecast/SaleImport/SaleImport.php, _underscore/Component/Forecast/Db/Db.php, worker2/Worker/Netsuite/Invoice.php, worker2/Worker/Netsuite/CashSale.php, worker2/Worker/Netsuite/CreditMemo.php, worker2/Worker/Netsuite/CashRefund.php, worker2/Worker/Netsuite/Opportunity.php, worker2/Worker/Netsuite/SalesOrder.php |
+| [_Model magic-field access (__get without __isset)](features/model-magic-field-access.md) | `_Model` exposes DB columns as "magic" properties via `__get()`, but it defines **no** `__isset()`. | _underscore/Model/Core/Model.php |
 | [NetSuite REST Client (_Component_Api_Netsuite) — record writes & SuiteQL](features/netsuite-rest-client.md) | `_Component_Api_Netsuite` is the **2.0 `_underscore` NetSuite REST client** — the shared primitive every worker2/api2 NetSuite caller uses for record GETs, Suit | _underscore/Component/Api/Netsuite/Netsuite.php |
 | [Per-Client Database Connections & the Local Logs Trap](features/per-client-database-connections.md) | When `_underscore` serves a request for a client it opens **three distinct per-client database connections**, not one. | _underscore/Database.php, _underscore/ApiRequest.php, _underscore/Model/Client/Logs/Api.php |
 | [Recursive Item Fulfillments (upstream mirroring)](features/recursive-item-fulfillments.md) | In a multi-tier supply chain a sales order (SO) spawns a purchase order (PO) that becomes another SO downstream, and so on. | _underscore/Model/Client/ItemFulfillment.php, _underscore/Model/Client/ItemFulfillmentItem.php, _underscore/Model/Client/ItemFulfillmentItemUnit.php, _underscore/Model/Client/ItemFulfillmentPackage.php, _underscore/Model/Compass/AdvanceShippingNotice.php, dbchanges2/Core/2026-02-13 - 75601 - RecursiveItemFulfillmentCreation.sql, dbchanges2/Core/2026-06-04 - RecursiveItemFulfillmentPut.sql |

package/knowledge/2.0/apps/_underscore/features/forecast-sale-import.md

@@ -0,0 +1,157 @@
+---
+title: Forecast.Sales NetSuite import engine (real-time webhook)
+framework: "2.0"
+repo: _underscore
+project: _Underscore
+client: shared
+type: feature
+status: active
+updated: 2026-06-24
+owners: [dfranks]
+files:
+  - _underscore/Component/Forecast/SaleImport/SaleImport.php
+  - _underscore/Component/Forecast/Db/Db.php
+  - worker2/Worker/Netsuite/Invoice.php
+  - worker2/Worker/Netsuite/CashSale.php
+  - worker2/Worker/Netsuite/CreditMemo.php
+  - worker2/Worker/Netsuite/CashRefund.php
+  - worker2/Worker/Netsuite/Opportunity.php
+  - worker2/Worker/Netsuite/SalesOrder.php
+related:
+  - ../architecture.md
+  - ../../worker2/architecture.md
+---
+
+## Summary
+Real-time importer that takes a NetSuite **sale** record and writes its lines into
+`Forecast.Sales` (the Forecast2 revenue table). Covers the four NetSuite sale record
+types: **invoice, cashSale, creditMemo, cashRefund**. It is the webhook-driven replacement
+for the SALES section of the legacy 5-minute pull cron
+(`worker/crons/toga2/forecast2/common_import_sales_from_netsuite.php`), and mirrors the
+already-shipped SalesOrder (open-orders) and Opportunity webhook handlers.
+
+The shared engine is `_Component_Forecast_SaleImport`; four thin worker2 handlers
+(`_Worker_Netsuite_{Invoice,CashSale,CreditMemo,CashRefund}`) just delegate to it.
+
+**Critical, non-obvious facts (read before touching this):**
+- **Sign convention differs from the cron** — the raw REST record is all-positive, so the
+  webhook applies the sign factor **uniformly to every line**, not just shipping. Copying
+  the cron's sign handling reintroduces the credit-memo sign bug. (See Sign convention.)
+- The engine is a `_Component_*` class and therefore **must live in `_underscore`**, not in
+  worker2 — the autoloader rejects a `_Component_*` loaded from a project path. (See Gotchas.)
+
+## Key files / entry points
+| File | Role |
+|---|---|
+| `_underscore/Component/Forecast/SaleImport/SaleImport.php` | the engine (shared body for all four types) |
+| `_underscore/Component/Forecast/Db/Db.php` | shared NS-REST + sublist-pagination helpers |
+| `worker2/Worker/Netsuite/Invoice.php` etc. | four thin handlers; `post`/`put` → `sync`, `delete` → `removeAll` |
+
+Each handler is `abstract class _Worker_Netsuite_<Type> implements
+_Interface_Static_Webhook_Netsuite`. The router (`_Worker_NetSuite::Webhook`) PascalCases
+the inbound `recordType` into the class name; `invoice`/`cashSale`/`creditMemo`/`cashRefund`
+map 1:1, so **no router change is needed** to add these.
+
+Engine public surface: `sync(int $internalId, string $type)` and
+`removeAll(int $internalId)`. post/put → `sync`; delete → `removeAll`.
+
+## How it works
+Per-record flow in `sync`:
+1. REST GET the record (`expandSubResources=true`) via `_Component_Forecast_Db::fetchRecord`.
+2. **Per-type status gate** → if excluded, call `removeAll` and stop. Exclusions: invoice
+   `Voided`/`Rejected`; cashSale `Unapproved Payment`; creditMemo `Voided`; cashRefund has
+   no gate.
+3. If `shippingCost != 0`, append a **synthetic SHIPPING line at lineNumber 0** using
+   NetSuite item internalId **13500** (a real `Forecast.Items` row).
+4. Per line: resolve the item (with self-heal — see below); skip `itemGroup` items
+   (no line revenue).
+5. Guarded upsert keyed on `(netsuiteTransactionInternalId, lineNumber)`.
+6. Reconcile-delete any lines NetSuite no longer returns.
+7. Commit `DB_FORECAST`.
+
+`removeAll(internalId)` deletes all rows for that transaction (used by delete events and by
+the status gate).
+
+### Shared helpers on `_Component_Forecast_Db` (dedup)
+- `fetchRecord(route, label)` — NS REST GET + decode.
+- `collectItemLines(record)` + `nextPageRoute(links)` — `rel=next` sublist pagination.
+
+`Opportunity.php` and `SalesOrder.php` were refactored onto these shared versions; their
+private `fetchRecord`/`collectAllItemLines`/`nextPageRoute` copies (and SalesOrder's
+orphaned `MAX_SUBLIST_PAGES` const) were deleted.
+
+## Sign convention (the load-bearing decision)
+The **raw REST record** returns each line `amount`/`costEstimate` **POSITIVE for all four
+types** (verified by live probe 2026-06-24 against NS account 1095849: creditMemo lines
++350/+400/+700/…, cashRefund +885, invoice all positive). The engine therefore applies the
+sign factor **uniformly**:
+- `factor = -1` for **creditMemo + cashRefund**, `+1` for **invoice + cashSale**
+- `revenue = amount * factor`
+- `profit  = (amount - costEstimate) * factor`
+- shipping line `amount = shippingCost * factor`
+
+This is the **opposite of the legacy cron**, which reads the pre-signed listSales 1.0 shim
+(already `-foreignamount`) and so applies the factor **only** to the synthetic shipping
+line. **Do not copy the cron's sign handling into the webhook** — it reintroduces the
+~$470K credit-memo sign bug (credits stored positive). The cron is not authoritative for
+the raw-REST path. Confirmed end-to-end against the local Forecast mirror (creditMemo
+revenue stored -350..-600; cashRefund revenue -885 / profit -78; invoice positive).
+
+> A reviewer may flag "profit double-signs the factor" — false positive:
+> `(amount*factor) - (costEstimate*factor) == (amount - costEstimate)*factor`.
+
+## Item self-heal
+When a sale line references a NetSuite item not yet in `Forecast.Items`, the engine pulls it
+on demand via `_Worker_Netsuite_Item::syncItem()` (the same method the open-orders handler
+uses) and then writes the line — instead of the cron's silent skip. Failure semantics:
+- `syncItem` throws **`RuntimeException`** for a genuinely unmappable item (no Forecast enum
+  value / absent from NetSuite) → engine catches it and **skips that one line** (logging it),
+  matching cron tolerance.
+- A real infrastructure failure is raised by `_Component_Api_Netsuite::send` as a **plain
+  `Exception`** (superclass of `RuntimeException`) → **not caught** → propagates and fails
+  the job for retry.
+- `itemGroup` items carry no line revenue and are skipped.
+
+## Data model — Forecast.Sales schema facts
+Prod `Forecast.Sales` writable columns: `netsuiteTransactionType`
+(enum `'invoice','cashSale','creditMemo','cashRefund'`), `netsuiteTransactionInternalId`,
+`tranDate`, `tranNumber`, `customerId`, `leadSource`, `salesRepEmployeeId`, `itemId`,
+`lineNumber`, `revenue`/`profit` `decimal(14,2)`, `createdFromNetsuiteTransactionInternalId`.
+- **No `amountDue` and no `dtPendingBilling` column** in prod (no staged dbchanges2 adds
+  them) → this importer does **not** write amountDue. The engine is structured so adding it
+  later is a one-line change (value map + tracked-columns + change-detection SELECT).
+- **No `classificationId` column** (unlike OpenOrderItems) → classification is not resolved
+  or written for Sales.
+- **No unique index** on `(netsuiteTransactionInternalId, lineNumber)`; the composite
+  `Sales_netsuiteTransactionType_IDX` leads with `netsuiteTransactionType`. Because there is
+  no unique key, inserts use a guarded `INSERT ... SELECT ... FROM DUAL WHERE NOT EXISTS(...)`
+  for idempotency. This reduces but does not fully eliminate concurrent-duplicate risk;
+  serialized-per-internalId + reconcile-delete close the gap. A real unique index is
+  **deliberately deferred**.
+
+## Integration mechanism — the NetSuite AMQ enqueuer is per-record-type
+The User Event enqueuer `customscript_ue_amq_enqueue`
+(`test/@dave/NetSuite/api-message-queue/ue_api_msg_queue_enqueue.js`) must be **deployed on
+each record type** for that type's create/edit/delete to enqueue a webhook. Inbound sale
+events therefore require this one script deployed on **Invoice, Cash Sale, Credit Memo, and
+Cash Refund**. The drainer (`customscript_ss_amq_drain`) is record-type-agnostic and needs
+no per-type deployment.
+
+The enqueuer's `RECORD_TYPE_MAP` (lowercase NS `record.type` → camelCase `recordType` the
+worker2 router PascalCases) already maps the four sale types 1:1. Note: NetSuite emits item
+events as specific **subtypes** (`inventoryItem`, `nonInventoryResaleItem`, `kitItem`,
+`itemGroup`, …) with no generic `item` type — collapsing those subtype VALUES to `'item'`
+would be needed only for a future real-time item webhook, **not** for this Sales importer
+(which keeps items fresh via the hourly item pull cron plus the inline self-heal).
+
+## Gotchas / known issues
+- **`_Component_*` classes must live under the `_underscore` framework root, never a project
+  repo.** The autoloader rejects a `_Component_*`/`_Model_*` loaded from a project path
+  (e.g. `./` under worker2) with "namespace … has not been defined" — at **class-load
+  (runtime), not `php -l`**. So this engine lives in `_underscore` next to
+  `_Component_Forecast_Db` even though only worker2 uses it; it references the worker2 class
+  `_Worker_Netsuite_Item`, resolved lazily at runtime in the worker2 context.
+- The cron's sign handling is not portable here — see Sign convention.
+
+## Change history
+- 2026-06-24 — Built the Forecast.Sales real-time webhook importer (shared `_Component_Forecast_SaleImport` engine + four thin worker2 handlers), replacing the legacy cron SALES section; decided the uniform-factor sign convention against the raw REST record; deduped `fetchRecord`/sublist pagination onto `_Component_Forecast_Db`. (dfranks)

package/knowledge/2.0/apps/_underscore/features/model-magic-field-access.md

@@ -0,0 +1,57 @@
+---
+title: _Model magic-field access (__get without __isset)
+framework: "2.0"
+repo: _underscore
+project: _Underscore
+client: shared
+type: feature
+status: active
+updated: 2026-06-25
+owners: ["jcardinal"]
+files:
+  - _underscore/Model/Core/Model.php
+related:
+  - ../../api2/features/language-translation-layer.md
+---
+
+## Summary
+
+`_Model` exposes DB columns as "magic" properties via `__get()`, but it defines **no** `__isset()`.
+Because PHP does not route `isset()` / null-coalescing through `__get()`, any `isset($model->field)` or
+`$model->field ?? null` on a magic (DB) field is **always** `false` / `null` — even when the column
+exists and has a value. And a bare `$model->field` read for a column that is **not** on the model
+**throws**. This bites any code that probes for an optional/conditional field on a generic model.
+
+## How it works
+
+- `_Model::__get($name)` resolves a configured DB field and returns its value; for an unconfigured
+  field it throws (not a silent null).
+- There is **no** `_Model::__isset()`, so PHP's `isset()`/`empty()`/`??` short-circuit to "not set"
+  for every magic field before `__get` is ever consulted. This is a PHP language rule, not a bug in
+  the value.
+
+**Safe pattern for a possibly-absent field on a generic model:**
+
+```php
+if (array_key_exists('uuid', $model->getFieldConfig())) {
+    $uuid = $model->uuid; // safe: __get won't throw, field is known to exist
+}
+```
+
+Check `array_key_exists('field', $model->getFieldConfig())` first, then read via `__get`. Do **not**
+gate on `isset($model->field)` or `$model->field ?? $default` — both silently misbehave.
+
+## Gotchas / known issues
+
+- `isset($model->magicField)` / `$model->magicField ?? null` are **always** false/null for DB-backed
+  magic fields. Use `getFieldConfig()` + `array_key_exists` to test presence.
+- A bare `__get` on an unconfigured field **throws** — never read a maybe-absent field without the
+  `getFieldConfig()` guard.
+- This surfaced as a missing `uuid` in the API translation-layer fallback warning — see
+  [Language Translation Layer](../../api2/features/language-translation-layer.md).
+
+## Change history
+
+- 2026-06-25 — Documented the `__get`-without-`__isset` gap and the `getFieldConfig()` +
+  `array_key_exists` safe-read pattern, discovered while debugging a missing `uuid` in the API2
+  translation fallback warning. (jcardinal)

package/knowledge/2.0/apps/api2/INDEX.md

@@ -3,7 +3,7 @@
 | Doc | Summary | Files |
 |-----|---------|-------|
 | [API (api2 / TOGa API v2) Architecture](architecture.md) | `api2` is the backend powering the public **TOGa 2.0 API**. | api2/Controller/Index.php, api2/Component/Api/V2/V2.php, api2/Component/Api/Cxml/Cxml.php, api2/Component/Api/V2/Response/Response.php, api2/Config/ |
-| [Language Translation Layer (audience.language + sidecar tables)](features/language-translation-layer.md) | Serves the same TOGa data (Item title/description/longDescription, expanding later) in multiple languages without forking the schema or breaking English consume | api2/Component/Api/V2/V2.php, _underscore/Model/Core/Setting.php, _underscore/Model/Core/RecordField.php, _underscore/Model/Core/DefaultGlobalSetting.php, _underscore/Model/Client/ItemTranslation.php, dbchanges2/Client/2026-06-23a - ItemTranslations.sql, dbchanges2/Client/2026-06-23b - ItemTranslationsAcl.sql, dbchanges2/Core/2026-06-23a - RecordFieldsTranslationColumn.sql, dbchanges2/Core/2026-06-23b - ItemTranslationsRecord.sql |
+| [Language Translation Layer (audience.language + sidecar tables)](features/language-translation-layer.md) | Serves the same TOGa data (Item title/description/longDescription, expanding later) in multiple languages without forking the schema or breaking English consume | api2/Component/Api/V2/V2.php, api2/Component/Api/V2/Response/Response.php, _underscore/Model/Core/Setting.php, _underscore/Model/Core/RecordField.php, _underscore/Model/Core/DefaultGlobalSetting.php, _underscore/Model/Client/ItemTranslation.php, dbchanges2/Client/2026-06-23a - ItemTranslations.sql, dbchanges2/Client/2026-06-23b - ItemTranslationsAcl.sql, dbchanges2/Core/2026-06-23a - RecordFieldsTranslationColumn.sql, dbchanges2/Core/2026-06-23b - ItemTranslationsRecord.sql |
 | [POST + JSON-body args for scripted APIs](features/scripted-api-post-body-args.md) | The V2 engine can run a Record Script (scripted API) for a **POST** request, and a scripted API can receive its arguments from the **JSON request body** instead | api2/Component/Api/V2/V2.php |
 | [Tickets API (/v2/tickets)](features/tickets-api.md) | The generic ticket endpoint of the 2.0 REST API. | Component/Api/V2/V2.php |
 | [AWS CodePipeline Deployment via CodeConnections (GitHub → Elastic Beanstalk)](workflows/codepipeline-codeconnections-deploy.md) | 2.0 apps (`api2`, `_underscore`) are deployed through **AWS CodePipeline**. |  |

package/knowledge/2.0/apps/api2/features/language-translation-layer.md

@@ -6,10 +6,11 @@ project: API
 client: shared
 type: feature
 status: active
-updated: 2026-06-23
+updated: 2026-06-25
 owners: ["jcardinal"]
 files:
   - api2/Component/Api/V2/V2.php
+  - api2/Component/Api/V2/Response/Response.php
   - _underscore/Model/Core/Setting.php
   - _underscore/Model/Core/RecordField.php
   - _underscore/Model/Core/DefaultGlobalSetting.php
@@ -20,6 +21,7 @@ files:
   - dbchanges2/Core/2026-06-23b - ItemTranslationsRecord.sql
 related:
   - ./acl-permission-chain.md
+  - ../../_underscore/features/model-magic-field-access.md
 ---
 
 ## Summary
@@ -55,6 +57,19 @@ persona** (in the user's persona order) that sets it wins. The resolved code is
 response as `audience.language`. API-credential auth gets no language. Token refresh copies the claim,
 so a language change requires re-authentication.
 
+**Invalid-language hard failure (auth time).** The resolved code is validated against the client's
+`Languages` table. An **unset/empty** setting defaults to `en` (no error). But a **non-empty** code
+that does **not** exist in `Languages` now **fails authentication** with HTTP 400
+`EV-16 DEFINED_MESSAGE_ERROR_INVALID_LANGUAGE_SETTING` (validation group, defined in `Response.php`),
+with the offending `language` code in the message `identifiers` — instead of silently falling back to
+`en`. A misconfigured language must surface loudly, not silently degrade.
+
+**Auth-mint status finalization (subtle).** The auth success path sets `status = 201` and attaches the
+tokens. EV-16 is signalled by a local flag `$invalidLanguageSetting` set at the resolution site; the
+finalization branches `if (empty($invalidLanguageSetting))` → `201` + tokens, else
+`addDefinedMessage(EV-16)` + `data = null`. See Gotchas — do **not** convert this to an
+`is_null($this->response->status)` guard.
+
 **Which fields are translatable (metadata-driven).** `Core.RecordFields.translationRecordFieldId`
 (new column, positioned after `recordId`) points a source field's RecordField at the sidecar field's
 RecordField. `buildLookups`/RecordFields-load resolves this into
@@ -65,7 +80,10 @@ serialization site (top-level full-model, custom-fields, FK child, both inherent
 `getTranslatedFieldValue($record, $field, $sourceModel, $defaultValue)` is called. When a non-base
 language is active and the field is translatable, it loads the sidecar row for that source row +
 `languageId` (cached per row so multiple fields = one load) and returns the sidecar value if non-null;
-otherwise it returns the English default and queues a deduped `W*` warning.
+otherwise it returns the English default and queues a fallback warning. The warning now carries the
+missing record's `uuid` in its `identifiers` and dedupes per-field-**and**-per-record
+(key `recordFieldId:uuid`) rather than once-per-field — so every record lacking a translation for a
+field is reported individually.
 
 **Write path.** On create and update, `extractTranslationWrites()` pulls translatable fields out of
 the write set for a non-base language (so the English source is never overwritten), and after the
@@ -96,6 +114,26 @@ None — uniform across all clients. The sidecar table + ACL ship via `dbchanges
   per-field fallback warning signals the English fallback.
 - The base language is `en`; when the resolved language is `en` (or API auth) all translation logic is
   skipped and responses are byte-identical to pre-feature.
+- **"Why isn't my language setting applying?"** A `ClientGlobalSettings` row with `isOverridable = 0`
+  **locks** the value against all downstream persona/user layers — a `UserGlobalSettings` (or persona)
+  override never wins while the client-global layer is locked. This is by design (the 8-layer cascade
+  with `isOverridable` locking). To let user/persona overrides apply, the locking layer must be
+  `isOverridable = 1` (or its value cleared). The cascade itself is correct — this is a data-config
+  gotcha, not a code bug.
+- **Namespace gotcha in `V2.php` (`namespace api;`).** The api-namespaced classes
+  (`_Component_Api_V2_Response`, `_Component_Api_V2_Response_Message`) must be referenced **unqualified**
+  (resolves to `api\…`) or with the full `\api\_Component_Api_V2_Response_Message`. A bare leading
+  backslash (`\_Component_Api_V2_Response_Message`) forces the global namespace and throws
+  `EO-1 "Could not find required file"` via the autoloader. The translation fallback-warning code hit this.
+- **Do NOT guard the auth-mint finalization with `is_null($this->response->status)`.** The auth response
+  auto-adds client `name` + user `firstName`/`lastName` and runs `processRoutePairs()`, which sets
+  `$this->response->status` to `200` **before** finalization. An `is_null` guard there suppresses the
+  `201` + tokens and yields a broken `200`/`data:null` login. Branch on the explicit
+  `$invalidLanguageSetting` flag instead.
+- Reading a possibly-absent magic field off a generic `_Model` needs `array_key_exists(...)` +
+  `__get` — `isset()`/`?? null` always read false/null. See
+  [_Model magic-field access](../../_underscore/features/model-magic-field-access.md); this was the
+  cause of the uuid not appearing in the fallback warning.
 - Migrations not yet executed at time of writing; needs live verification.
 
 ## Change history
@@ -103,6 +141,14 @@ None — uniform across all clients. The sidecar table + ACL ship via `dbchanges
 - 2026-06-23 — Initial build: audience.language + JWT embedding, ItemTranslations sidecar + metadata +
   full ACL chain, and translation-aware read/write at the API layer. Also fixed a latent autoload bug
   by renaming `DefaultFlobalSetting.php` → `DefaultGlobalSetting.php`. (jcardinal)
+- 2026-06-25 — Added defined error `EV-16 INVALID_LANGUAGE_SETTING` (HTTP 400, in `Response.php`): a
+  non-empty language code absent from `Languages` now fails auth instead of silently falling back to
+  `en` (empty still defaults to `en`). Documented the auth-mint `201` finalization (branch on the
+  `$invalidLanguageSetting` flag, never an `is_null(status)` guard). Fixed the fallback-warning
+  namespace bug (no bare leading backslash on api-namespaced classes). Fallback warning now includes the
+  record `uuid` and dedupes per-record (`recordFieldId:uuid`). Documented the `isOverridable = 0`
+  client-global lock as a config gotcha. Discovered the `_Model` `__isset` gap behind the missing-uuid
+  bug (see linked _underscore doc). Live-tested on the local Compass DB. (jcardinal)
 
 ## Related docs
 

package/knowledge/INDEX.md

@@ -15,7 +15,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 
 ## 2.0 framework
 
-- **_underscore** (_Underscore) _(framework core)_ — 12 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
+- **_underscore** (_Underscore) _(framework core)_ — 14 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
 - **worker2** (Worker) — 14 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
 - **api2** (API) — 6 doc(s) → [2.0/apps/api2/INDEX.md](2.0/apps/api2/INDEX.md)
 - **dbchanges2** (Database Changes) _(framework core)_ — 2 doc(s) → [2.0/apps/dbchanges2/INDEX.md](2.0/apps/dbchanges2/INDEX.md)

package/package.json

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