toga-ai 1.0.727 → 1.0.729

package/knowledge/2.0/apps/api2/features/tableview-apiwhereclause-row-filtering.md

@@ -6,7 +6,7 @@ project: API
 client: shared
 type: feature
 status: active
-updated: 2026-07-15
+updated: 2026-09-01
 owners: ["bala"]
 files:
   - api2/Component/Api/V2/V2.php
@@ -14,6 +14,7 @@ files:
   - toga2-supply/src/api/toga.ts
 related:
   - ../../../clients/compass-usa/features/item-fulfillment-tracking-tableview.md
+  - ../../../clients/compass-usa/features/item-catalogs-and-duplicate-items.md
   - tableview-field-metadata.md
 ---
 
@@ -36,8 +37,9 @@ view with a migration and no application code.
 - **Consumption** — `toga2-supply/src/api/toga.ts` (~line 943-951): pushes the `apiWhereClause`
   literal string into `options.where.and`, and (~line 631-641) builds `options.join` / `ojoin`
   from the view's `TableViewJoins`.
-- **Parsing** — `api2/Component/Api/V2/V2.php::parseOptionsWhere` (~line 7574-7773): turns the
-  clause string into SQL.
+- **Parsing** — `api2/Component/Api/V2/V2.php::parseOptionsWhere` (~line 8200-8390, re-located
+  2026-09-01; it was ~7574 when this doc was first written, so search for the function name rather
+  than trusting the line number): turns the clause string into SQL.
 
 ## How it works
 
@@ -68,6 +70,22 @@ The field slot accepts a **raw SQL expression**, not just a plain column — e.g
 exclusion on the Compass fulfillment view): `(IFNULL(Items.assetTypeId,0):ne:<FEE id>)` — the
 `IFNULL(...,0)` keeps rows with a NULL FK from being silently dropped.
 
+### A single-condition clause is wrapped in parens too
+
+`parseOptionsWhere` **strips one leading `(` and one trailing `)` from the whole clause before it
+scans for top-depth commas** (V2.php ~line 8222-8229). Those outer parens are the group wrapper,
+not part of the first condition, so the house form for a one-condition filter is:
+
+```
+(Items.catalogId:eq:1)
+```
+
+The wrapper comes off first, leaving `Items.catalogId:eq:1`, which is then read as a plain
+condition — it is never mistaken for a nested group needing recursion. Write the parens; they match
+the existing Compass convention and the stored clauses stay uniform whether they hold one condition
+or five. (The "expression field must not start with `(`" gotcha below is about the *field slot* of a
+condition **after** the wrapper is removed — the two are not in conflict.)
+
 ### Join alias rule (which table-qualified name to use)
 
 In `_underscore/Model/Client/TableView.php` (~line 89-96), the **first** occurrence of a joined
@@ -77,6 +95,19 @@ referencing `Items.<field>` only binds correctly when the view joins `Items` **e
 Before writing a clause, confirm the target table is joined once, or qualify against the correct
 suffixed alias.
 
+**A view's base record is not a join, so it never gets a suffix.** Worked example — the shared
+`items` view (`TableViews.slug = 'items'`, `id 9`, `recordId 21` = `_Model_Client_Item`, route
+`items`; the same shape in `Client_Compass`, `Client_CompassCanada` and `Client_Quad`). Its four
+`TableViewJoins` are `joinRecordId` **20** Manufacturers, **33** ItemTypes, **32** AssetTypes and
+**34** ItemCategories, all INNER. `Items` appears only as the base record and is never re-joined,
+so the bare `Items.` qualifier is correct and there is no `_B`/`_C` to worry about. Check this the
+same way on any view before writing a clause: list the view's `TableViewJoins` and count how many
+resolve to the table you want to filter.
+
+Two schema notes for anyone writing the migration: `TableViews` has **no `name` or `tableName`
+column** in these client schemas — identify a view by its `slug` (UNIQUE) plus `recordId`, which is
+what makes `WHERE slug = 'items'` a safe, id-agnostic target across tenants.
+
 ## Data model
 
 - `TableViews.apiWhereClause` (TEXT, nullable) — the view-level row filter.
@@ -91,6 +122,8 @@ None — engine behavior. A specific client's view may carry its own `apiWhereCl
 
 - **Comma inside a function is safe.** The parser only splits conditions on top-depth commas, so
   a comma inside `IFNULL(x,0)` or `IN(...)` does not break the clause.
+- **A one-condition clause still needs its outer parens** — they are stripped before parsing, so
+  `(Field:eq:value)` and `Field:eq:value` behave identically; use the wrapped form for consistency.
 - **An expression field must NOT start with `(`.** A condition that starts with `(` is treated by
   the parser as a nested group and recursed into — so wrap an expression field in a function that
   starts with a letter (e.g. `IFNULL(...)`), never a bare parenthesized expression.
@@ -102,6 +135,15 @@ None — engine behavior. A specific client's view may carry its own `apiWhereCl
 
 ## Change history
 
+- 2026-09-01 — Recorded that the parser **strips one leading `(` and one trailing `)` from the whole
+  clause before splitting**, so the wrapped single-condition form `(Items.catalogId:eq:1)` is safe
+  and is the house convention (this was previously only documented for the multi-condition form).
+  Added a worked alias-verification example on the shared `items` view (id 9, recordId 21, four
+  INNER `TableViewJoins` 20/33/32/34, `Items` only as base record → bare `Items.` qualifier), noted
+  that `TableViews` carries no `name`/`tableName` column so `slug` is the id-agnostic target, and
+  re-pointed `parseOptionsWhere` at its current location (~8200, was ~7574). No code change —
+  verified while writing the catalog-1 filter migration for the `items` view in `Client_Compass`,
+  `Client_CompassCanada` and `Client_Quad`. (bala)
 - 2026-07-15 — Documented the end-to-end `apiWhereClause` row-filter mechanism (emission →
   consumption → `parseOptionsWhere` grammar), the operator→SQL table, the raw-expression field
   slot, the leading-paren / top-depth-comma parser behavior, and the `_underscore` join-alias

package/knowledge/2.0/apps/talos/features/aegra-api.md

@@ -6,8 +6,8 @@ project: TOGa IQ
 client: shared
 type: feature
 status: active
-updated: 2026-06-16
-owners: [akhokhani]
+updated: 2026-09-01
+owners: [akhokhani, apeterson]
 files:
   - talos/libs/aegra-api/src/aegra_api/main.py
   - talos/libs/aegra-api/src/aegra_api/settings.py
@@ -43,6 +43,8 @@ related:
   - ../architecture.md
   - mcp-servers.md
   - observability.md
+  - chat-frontend.md
+  - ../../toga25-supply/features/talos-integration.md
 ---
 
 ## Summary
@@ -202,5 +204,36 @@ None — uniform across clients. Per-tenant data isolation is enforced by
 - **Alembic password chars** — keep the `config.attributes` URL passing pattern
   in `env.py`; configparser interpolation will mangle `%` in passwords.
 
+### For browser clients (found 2026-09-01 wiring toga25-supply)
+
+- **⚠ CORS headers come back on the OPTIONS PREFLIGHT ONLY — not on the actual response.**
+  Verified from both a local dev origin (`http://nychh.dev.sandbox.togasupply:5173`) and a prod
+  origin (`https://nychh.togasupply.com`): the preflight returns
+  `access-control-allow-origin: *`, but the real `GET` carries **no `access-control-*` header at
+  all**. A browser therefore blocks every real response even when the service is perfectly healthy.
+  Reported to `akhokhani`; a server-side caller (curl, the old talos proxy route) never sees this.
+- **`AUTH_TYPE=togahub` accepts an api2 JWT issued for a NON-TogaHub client.** Confirmed with a
+  **toga25-supply** token whose `aud` was a supply hostname (`https://<tenant>.togasupply.com`) and
+  whose `iss`/`sub` were `http://api.beta.togahub.com` — `GET /assistants` succeeded. So a sibling
+  app needs **no** token exchange and no `/auth/delegator` handoff; it passes the token it already
+  holds. (Do not read `aud` as an audience check — it is not enforced.)
+- **`assistant_id` is per-tenant. Discover it, never pin it in env.**
+  `GET /assistants?limit=100&offset=0` returns
+  `{ assistants: [{ assistant_id, name, graph_id, metadata: { customer_facing, read_only,
+  tenant_slug } }], total }`. Pick on `metadata.customer_facing === true`. Send **no body and no
+  `Content-Type`** — `fetch` forbids a body on GET and a JSON content-type only adds a preflight.
+- **An unregistered tenant gets a clean 403 on every call even with a valid token** (control-plane
+  DB / `tenant_router` LRU). Provisioning is explicit; there is no auto-create.
+- *Point-in-time note, may be stale:* on **2026-09-01** `https://api.beta.togaiq.com` returned
+  **502** on `/health`, `/info` and `/assistants` (nginx up, app behind it down) after a clean 401
+  ~10 minutes earlier. Re-probe `/info` before assuming a client bug.
+
 ## Change history
+- 2026-09-01 — Added a **browser-client** gotcha set found while wiring toga25-supply: Aegra returns
+  CORS headers **on the OPTIONS preflight only**, so a browser blocks every real response even on a
+  healthy service (server-side callers never see it); `AUTH_TYPE=togahub` **accepts an api2 JWT
+  issued for a non-TogaHub client** (`aud` is not enforced), so sibling apps need no token exchange;
+  and `assistant_id` is **per-tenant** and must be discovered via `GET /assistants` (pick on
+  `metadata.customer_facing`, send no body/`Content-Type`). Also recorded a dated 502 outage
+  observation on `api.beta.togaiq.com`. (apeterson)
 - 2026-06-16 — Initial aegra-api feature doc (HTTP layer + execution pipeline). (akhokhani)

package/knowledge/2.0/apps/talos/features/chat-frontend.md

@@ -6,7 +6,7 @@ project: TOGa IQ
 client: shared
 type: feature
 status: active
-updated: 2026-08-28
+updated: 2026-09-01
 owners: [apeterson]
 files:
   - talos/package.json
@@ -154,15 +154,26 @@ rather than an assumption.
 ## Gotchas
 
 - **`@langchain/react` is a different package** from what this app uses. It is a newer wrapper
-  (v1.0.33) over the same `@langchain/langgraph-sdk`, and it adds a `@langchain/core ^1.1.48` peer
-  plus media hooks/players. Do not assume talos validates it — talos uses the SDK's own
-  `/react` subpath.
+  (v1.0.33) over the same `@langchain/langgraph-sdk`, and it adds media hooks/players. Do not assume
+  talos validates it — talos uses the SDK's own `/react` subpath.
+- **⚠ Correction (verified 2026-09-01): `@langchain/core` is NOT an extra peer of
+  `@langchain/react`.** This doc previously said choosing the SDK's `/react` subpath meant one fewer
+  peer. It does not. **`@langchain/langgraph-sdk@1.10.0` declares `@langchain/core: ^1.1.48` as a
+  required (non-optional) peer itself** — `react`/`react-dom` are the optional ones. Symptom when
+  it is absent: Vite/esbuild dep-optimize hard-fails with `Could not resolve
+  "@langchain/core/messages"` and the dev server exits. The **decision** to use the SDK subpath
+  still stands (proven in-house, smaller surface) — only the "one fewer peer" reason was wrong.
 - **Do not copy `nuqs`** into a non-Next app (see above).
 - **`env.ts` is the only sanctioned env read** ("never access `process.env` directly elsewhere") and
   `validateEnv()` throws at startup on missing vars. Keep new env reads inside it — but note its
   comments have already drifted from its values once.
 
 ## Change history
+- 2026-09-01 — Correction only (no talos code change): the recorded rationale that
+  `@langchain/langgraph-sdk/react` means **one fewer peer** than `@langchain/react` is **wrong** —
+  the SDK declares `@langchain/core ^1.1.48` as a required peer itself, and omitting it hard-fails
+  Vite dep-optimize with `Could not resolve "@langchain/core/messages"`. The package choice itself
+  is unchanged. Found while building the same stack in toga25-supply. (apeterson)
 - 2026-08-28 — Documented the previously-undocumented TOGa IQ chat front-end: `useStream` from
   `@langchain/langgraph-sdk/react` wrapped in an app-owned context, the browser's **direct
   cross-origin call to Aegra** (proving a static SPA needs no server proxy) and the vestigial

package/knowledge/2.0/apps/toga-blox/INDEX.md

@@ -11,7 +11,7 @@
 | [Primary Table templates (server/client, sizing, virtualization)](features/primary-table-templates.md) | `src/templates/PrimaryTable/` is the **production, wired-up table** built on the [Table component](table.md). | toga-blox/src/components/Table/themeConfig/toga.module.css, toga25-supply/src/themeConfig.json, toga-blox/src/templates/PrimaryTable/PrimaryTable.tsx, toga-blox/src/templates/PrimaryTable/PrimaryTableServerTemplate.tsx, toga-blox/src/templates/PrimaryTable/PrimaryTableClientTemplate.tsx, toga-blox/src/templates/PrimaryTable/PrimaryTableHeaderCell.tsx, toga-blox/src/templates/PrimaryTable/PrimaryTableBodyCell.tsx, toga-blox/src/templates/PrimaryTable/PrimaryTableRow.tsx, toga-blox/src/templates/PrimaryTable/PrimaryTableExpandableRow.tsx, toga-blox/src/templates/PrimaryTable/types.ts |
 | [TableRecordModal (record-detail modal shell)](features/table-record-modal.md) | `TableRecordModal` is a **generic, presentational modal shell** for showing a single table record (row) in detail — typically opened from a table row click. | toga-blox/src/components/TableRecordModal/TableRecordModal.tsx, toga-blox/src/components/TableRecordModal/index.ts, toga-blox/src/components/TableRecordModal/tableRecordModal.module.css |
 | [Table component (cells, action cells, filters & sorts, hooks, theming)](features/table.md) | The `Table` component (`src/components/Table/`) is the **TanStack Table v8** building block behind the [Primary Table templates](primary-table-templates.md). | toga-blox/src/components/Table/hooks/useFetchTablePageMeta.ts, toga-blox/src/api/types.ts, toga-blox/src/components/Table/index.ts, toga-blox/src/components/Table/types.ts, toga-blox/src/components/Table/utils/buildTanstackColumns.tsx, toga-blox/src/components/Table/utils/resolveCellType.tsx, toga-blox/src/components/Table/components/cellTypes, toga-blox/src/components/Table/components/actionCells, toga-blox/src/components/Table/components/columnFiltersAndSorts, toga-blox/src/components/Table/hooks, toga-blox/src/components/Table/themeConfig |
-| [Talos AI-Assistant Component (launcher + docked/drawer chat panel)](features/talos-assistant.md) | `Talos` is a **shared, pure-UI** AI-assistant component in `@agilant/toga-blox`: a header launcher button (`TalosLauncher`) plus a chat panel (`TalosPanel`) tha | toga-blox/src/components/Talos/TalosLauncher.tsx, toga-blox/src/components/Talos/TalosPanel.tsx, toga-blox/src/components/Talos/TalosMessage.tsx, toga-blox/src/components/Talos/types.ts, toga-blox/src/components/Talos/theme.ts, toga-blox/src/components/Talos/helpers.tsx, toga-blox/src/components/Talos/stub.ts, toga-blox/src/components/Talos/Talos.module.css, toga-blox/src/components/Talos/index.ts, toga-blox/src/components/index.ts |
+| [Talos AI-Assistant Component (launcher + docked/drawer chat panel)](features/talos-assistant.md) | `Talos` is a **shared, pure-UI** AI-assistant component in `@agilant/toga-blox`: a header launcher button (`TalosLauncher`) plus a chat panel (`TalosPanel`) tha | toga-blox/src/components/Talos/TalosLauncher.tsx, toga-blox/src/components/Talos/TalosPanel.tsx, toga-blox/src/components/Talos/TalosMessage.tsx, toga-blox/src/components/Talos/types.ts, toga-blox/src/components/Talos/theme.ts, toga-blox/src/components/Talos/helpers.tsx, toga-blox/src/components/Talos/stub.ts, toga-blox/src/components/Talos/Talos.module.css, toga-blox/src/components/Talos/index.ts, toga-blox/src/components/Talos/TalosPanel.test.tsx, toga-blox/src/components/index.ts |
 | [Toaster — host-token styling contract](features/toaster.md) | The blox `Toaster` is a CSS-Module component whose every visual property reads a `--toaster-*` custom property supplied by the **host app**. | toga-blox/src/components/Toaster/Toaster.module.css, toga-blox/src/components/Toaster/Toaster.tsx, toga-blox/src/components/Toaster/ToasterContext.tsx, toga2-commerce/src/styles/index.css, toga2-commerce/src/components/Toasters/ToasterList.tsx |
 | [Dynamic npm Publish Pipeline (branch → channel)](workflows/dynamic-publish-pipeline.md) | How `@agilant/toga-blox` (checkout folder `toga-blox-npm`, registry repo key `toga-blox`) publishes a per-environment npm **channel** (dist-tag) from a `_<mode> | toga-blox/.github/workflows/publish.yml, toga-blox/package.json, toga-blox/src/utils/getFontAwesomeIcon.tsx |
 | [Landing a Large Long-Lived Feature Branch (merge, never rebase)](workflows/landing-a-large-feature-branch.md) | The procedure for landing a long-lived, very large feature branch (months old, hundreds of commits) into `_production` in `toga-blox-npm`. | toga-blox/package.json, toga-blox/.github/workflows/publish.yml |

package/knowledge/2.0/apps/toga-blox/features/talos-assistant.md

@@ -6,7 +6,7 @@ project: TOGa Blox
 client: shared
 type: feature
 status: active
-updated: 2026-08-28
+updated: 2026-09-01
 owners: [apeterson, tcox]
 files:
   - toga-blox/src/components/Talos/TalosLauncher.tsx
@@ -18,6 +18,7 @@ files:
   - toga-blox/src/components/Talos/stub.ts
   - toga-blox/src/components/Talos/Talos.module.css
   - toga-blox/src/components/Talos/index.ts
+  - toga-blox/src/components/Talos/TalosPanel.test.tsx
   - toga-blox/src/components/index.ts
 related:
   - ../architecture.md
@@ -40,7 +41,11 @@ across toga25-supply, toga2-desk, toga2-commerce, and `ai-bdr`. Build once, reth
 
 The defining constraint: the component holds **no business logic and no `window.*` globals** —
 every side effect flows through an injected adapter, and every visual token is overridable.
-The real chat backend is a **later ticket**; `onSend` currently ships stubbed.
+
+Since **2026-09-01** the panel also has a **controlled mode**: the host passes `messages` /
+`isStreaming` / `onSubmit` / `onStop` / `connection` and owns the conversation entirely. That is how
+toga25-supply runs the live streaming Aegra backend. **Uncontrolled mode is unchanged** — `onSend`
+still ships stubbed for hosts that pass no `messages`.
 
 ## Architecture (the four load-bearing decisions)
 
@@ -131,15 +136,27 @@ button, dropping expanded mode) are variants, not theme overrides.
 (`"comfortable" | "compact"`), and possibly a launcher `variant` + optional panel-mode props.
 Open questions were handed to the UX/UI team.
 
-## Where the code lives (status 2026-08-27 — check before planning around it)
+## Where the code lives — TWO divergent contracts on two branches (verified 2026-09-01)
+
+**Talos is on NO mainline branch.** `origin/_main`, `_production`, `_sandbox-client`, `_sandbox-dev`
+and `_beta` all lack `src/components/Talos/types.ts`. It is **in no npm dist-tag** — `latest` is
+`1.0.317`, `production` is `1.1.1-production.139`, neither contains Talos.
+
+| Branch | Contract |
+|---|---|
+| `origin/TRUE-80692` | **NARROW** — `paras` required; no `message` / `suggestions` / `cta`; `expanded` / `width` required; no `variant` / `features` |
+| `origin/TRUE-80692-BDR` | **WIDENED** — everything the drawer work added |
 
-- **Talos exists only on `origin/TRUE-80692`** (apeterson; 2 commits 08-20 plus a merge of
-  `_production` on 08-27). It is **not on the default branch** and **not in any npm dist-tag** —
-  `latest` is `1.0.317`, `production` is `1.1.1-production.139`, neither contains Talos.
-- `onSend` is still the **stub**; peers still cap React at `^18`.
-- The blox test suite on `TRUE-80692` has **40 pre-existing failures unrelated to Talos** — the
-  same 40 fail with the Talos changes stashed. Do not read them as a regression from this work.
-- The drawer variant itself was **uncommitted working tree** at capture (2026-08-27).
+> **Correction to the 2026-08-27 record:** tcox's widening commit `484e2a6` is on
+> **`TRUE-80692-BDR`**, *not* on the ticket branch `TRUE-80692`. Anyone branching off
+> `TRUE-80692` expecting the drawer variant gets the narrow contract.
+
+The 2026-09-01 controlled-mode work was done on `features-talos-transferorders`, which **merged
+`origin/TRUE-80692-BDR`** first (merge verified not to touch `AdvancedSelect`).
+
+- Peers still cap React at `^18`.
+- The blox test suite has **~40 pre-existing failures unrelated to Talos** — the same 40 fail with
+  the Talos changes stashed. Do not read them as a regression from this work.
 
 ## The contract cannot express streaming — a real backend REQUIRES a contract change
 
@@ -161,19 +178,43 @@ Aegra/LangGraph backend (which streams tokens, emits tool calls, and surfaces HI
 see [TOGa IQ chat frontend](../../talos/features/chat-frontend.md)) means changing this component's
 props. That was accepted deliberately rather than shipping a non-streaming v1.
 
-**Agreed direction (DECIDED 2026-08-28, NOT yet implemented):** make `TalosPanel` **controlled** —
-the host passes `messages` / `isStreaming` / `onSubmit` / `onStop` — plus an optional
-`connection?: "connecting" | "ready" | "error"` defaulting to `"ready"`.
+## Controlled mode — BUILT 2026-09-01 (the TRUE-80692 contract change)
+
+Implemented on branch `features-talos-transferorders`. New **optional** props on `TalosPanelProps`:
+
+```ts
+messages?: TalosMessageModel[];
+isStreaming?: boolean;
+onSubmit?: (text: string) => void;
+onStop?: () => void;
+connection?: TalosConnection;              // new exported type
+// export type TalosConnection = "connecting" | "ready" | "error";   default "ready"
+```
+
+**Controlled mode is keyed off `messages` being PASSED AT ALL** — not off a `controlled` flag. So
+every existing consumer and `createTalosStubAdapter()` are untouched. That non-breaking property
+matters: **BDR is a live consumer today.**
+
+Behaviour when controlled:
+
+- The panel renders the **host's** messages and **never calls `adapter.onSend`**.
+- **It does not append optimistically.** The host's next `messages` already carries the user turn,
+  so appending would duplicate it.
+- **`history` and `newChat` are forced OFF** — they act on the panel's own conversation list, which
+  it no longer owns.
+- The composer is **disabled until `connection === "ready"`**, with placeholders
+  `"Connecting to Talos…"` (connecting) and `"Talos is unavailable right now."` (error).
+- The send button **swaps to a stop button** when `isStreaming && onStop`.
 
-Two properties make this safe for a published package:
+Why this shape was safe to add: `open` / `expanded` / `width` were *already* host-controlled props,
+so moving `messages` to the host is the same pattern, not a new one. And `connection` gives the
+panel a real "we never got a token to begin with" state — previously a thrown `onSend` was its only
+failure path.
 
-- **Non-breaking.** `connection` defaults to `"ready"`, so existing consumers and
-  `createTalosStubAdapter()` keep working untouched.
-- **Consistent with what is already here.** `open` / `expanded` / `width` are *already* controlled
-  props owned by the host; moving `messages` to the host is the same pattern, not a new one.
+### Tests (first ever for this component)
 
-The panel also needs real **"connecting" / "failed to connect"** states: today a thrown `onSend` is
-its *only* failure path, which cannot represent "we never got a token to begin with."
+`TalosPanel.test.tsx` — **8 Vitest + RTL tests**, all passing, including **two that pin
+uncontrolled behaviour as unchanged**. (Separate from the ~40 pre-existing unrelated suite failures.)
 
 **The stream itself does NOT belong in blox.** Per
 [frontend.md §21](../../../standards/frontend.md) (promote only after a 2nd consumer validates the
@@ -185,8 +226,18 @@ Rollup *"failed to resolve import"* for a component they never referenced). blox
 
 ## Gotchas
 
-- **`onSend` cannot stream** — see the section above. A live streaming backend needs the
-  `TRUE-80692` contract change, not just an adapter.
+- **⚠ `TalosMessage` reads a DIFFERENT field per role.** A `role: "user"` turn renders
+  **`message.text`**; a `role: "talos"` turn renders **`message.message` / `message.paras`**. Put a
+  user turn's text in `message` and you get an **empty bubble** — no error, no warning. This bit the
+  supply LangGraph mapper and was only caught by writing tests.
+  ```ts
+  { role: "user",  text }      // ✅ user turn
+  { role: "talos", message }   // ✅ assistant turn
+  ```
+- **`onSend` cannot stream** — use **controlled mode** (above). A live streaming backend needs the
+  controlled props, not a cleverer adapter.
+- **Tool calls and HITL interrupts still have no representation** in `TalosMessageModel`. A host
+  mapping from LangGraph must drop them. Surfacing them needs new blox props.
 - The real chat backend is a later blox ticket — `onSend` is stubbed here; do not assume live
   responses from blox alone. **A working implementation exists outside blox and is now wired to
   this component:** `bdr/src/lib/talosChat.ts` implements the same
@@ -212,6 +263,19 @@ Rollup *"failed to resolve import"* for a component they never referenced). blox
   currently consumes it via a local symlink.
 
 ## Change history
+- 2026-09-01 — **BUILT controlled mode** (the TRUE-80692 contract change, previously only decided):
+  optional `messages` / `isStreaming` / `onSubmit` / `onStop` / `connection` on `TalosPanelProps`
+  plus a new exported `TalosConnection` type. Controlled mode keys off **`messages` being passed at
+  all**, so every existing consumer and `createTalosStubAdapter()` are untouched — non-breaking
+  matters because **BDR is live on this component**. Controlled panels never call `adapter.onSend`,
+  never append optimistically (the host's next `messages` already has the user turn), force
+  `history`/`newChat` off, disable the composer until `connection === "ready"`, and swap send→stop
+  while streaming. Added the component's **first tests** (`TalosPanel.test.tsx`, 8 Vitest+RTL, two
+  pinning uncontrolled behaviour). FIXED a real rendering trap found by those tests: `TalosMessage`
+  reads **`text` for user turns** but **`message`/`paras` for Talos turns**, so a user turn written
+  to `message` renders an empty bubble. DISCOVERED the branch topology is not what was recorded —
+  Talos is on **no** mainline branch, and tcox's widening commit lives on **`TRUE-80692-BDR`**, not
+  on `TRUE-80692`; the two branches carry **divergent contracts**. (apeterson)
 - 2026-08-28 — Review only (no blox code change): established that the `onSend(text) =>
   Promise<TalosResponse>` contract **cannot express token streaming** — the 08-27 `message`/
   `suggestions`/`cta` additions widen the *payload* but it still resolves once — so a live

package/knowledge/2.0/apps/toga-blox/workflows/local-link-into-a-consumer-app.md

@@ -6,7 +6,7 @@ project: TOGa Blox
 client: shared
 type: workflow
 status: active
-updated: 2026-08-31
+updated: 2026-09-01
 owners: [tcox, apeterson]
 files:
   - toga-blox/package.json
@@ -45,6 +45,35 @@ npm creates a **junction** at `<app>/node_modules/@agilant/toga-blox` pointing a
 `mklink /J` by hand works too. Use a **junction, not `mklink /D`** — a directory symlink needs
 administrator rights; a junction does not.
 
+### 1a. ⚠ EVERY `npm install` in the consumer destroys the link — re-link after each one
+
+`npm install` (even installing an unrelated package) replaces the
+`node_modules/@agilant/toga-blox` **symlink** with the registry version. On toga25-supply that is
+`1.1.1-production.139`, which contains **no Talos at all**.
+
+The symptom looks nothing like a dependency problem:
+
+```
+Uncaught SyntaxError: The requested module
+'/node_modules/.vite/deps/@agilant_toga-blox.js' does not provide an export named 'TalosLauncher'
+```
+
+**Re-link (from the consumer root):**
+
+```bash
+rm -rf node_modules/@agilant/toga-blox
+ln -s ../../../toga-blox-npm node_modules/@agilant/toga-blox
+rm -rf node_modules/.vite
+# then restart the dev server
+```
+
+- **`ln -sfn` alone is NOT enough** when the path is a real directory — it creates the link
+  *inside* it. You must `rm -rf` first.
+- Clearing `node_modules/.vite` is required because the stale pre-bundle is served `immutable`
+  (see §2c).
+- Same rule after editing blox source: `npm run build` in `toga-blox-npm`, **then** clear
+  `node_modules/.vite` in the consumer.
+
 ### 2. Collapse to ONE React (the React 19 case)
 
 `toga-blox-npm/node_modules` ships its own `react` + `react-dom` **18.3.1**. Through a link,
@@ -207,6 +236,11 @@ The consumer reads blox's `dist`, so rebuild blox after every change.
   drags every component's CSS into the consumer bundle.
 
 ## Change history
+- 2026-09-01 — Recorded that **any `npm install` in the consumer silently replaces the blox symlink
+  with the registry version** (toga25-supply → `1.1.1-production.139`, which has no Talos), and that
+  the symptom is a misleading `does not provide an export named 'TalosLauncher'`. Added the re-link
+  recipe and the trap that **`ln -sfn` alone fails when the target path is a real directory** — it
+  creates the link inside it, so `rm -rf` first. (apeterson)
 - 2026-08-31 — Added the "is it actually linked?" check: `toga25-supply` is on a **real registry
   install** of `1.1.1-production.139` (`LinkType` empty), not a junction, so blox source edits reach
   it only through publish + pin bump; and recorded that the urgent-case **installed-`dist` patch** is

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

@@ -2,7 +2,7 @@
 
 | Doc | Summary | Files |
 |-----|---------|-------|
-| [TOGa 2.5 Supply — Architecture](architecture.md) | `toga25-supply` ("TOGa 2.5 Supply") is the **React/TypeScript frontend** for the 2.0 Supply application — an iteration and improvement of `toga2-supply`. | toga25-supply/src/main.tsx, toga25-supply/src/App.tsx, toga25-supply/src/routes.tsx, toga25-supply/src/fieldsConfig/index.ts, toga25-supply/src/fieldsConfig/useClientFields.ts, toga25-supply/src/layout/, toga25-supply/src/pages/, toga25-supply/src/hooks/useTableCellInteractions.ts |
+| [TOGa 2.5 Supply — Architecture](architecture.md) | `toga25-supply` ("TOGa 2.5 Supply") is the **React/TypeScript frontend** for the 2.0 Supply application — an iteration and improvement of `toga2-supply`. | toga25-supply/src/main.tsx, toga25-supply/src/App.tsx, toga25-supply/src/routes.tsx, toga25-supply/src/fieldsConfig/index.ts, toga25-supply/src/fieldsConfig/useClientFields.ts, toga25-supply/src/layout/, toga25-supply/src/pages/, toga25-supply/src/hooks/useTableCellInteractions.ts, toga25-supply/src/providers/TalosStreamProvider.tsx |
 | [Action-Button Rule Engine (Flag / Rule grammar)](features/action-button-rule-engine.md) | A declarative, fully config-driven rule engine that resolves the boolean-ish flags (`isEnabled`, `isVisible`, `isComplete`) on SalesOrder action-button options. | toga25-supply/src/pages/SalesOrders/helpers/evaluateEnableRule.ts, toga25-supply/src/pages/SalesOrders/helpers/evaluateEnableRule.test.ts, toga25-supply/src/pages/SalesOrders/helpers/buildPatchedTenantFields.ts, toga25-supply/src/layout/RecordApprovalModal/view/ApprovalFlowDetailInputs.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderApprovalModalsLayout/viewModel/FIELDS/COMPASS/approvalActionFields.json, toga25-supply/src/pages/SalesOrders/view/SalesOrderApprovalModalsLayout/viewModel/FIELDS/COMPASSCANADA/approvalActionFields.json, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/viewModel/useSalesOrderRecordModalLayoutModel.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderApprovalModalsLayout/viewModel/useApprovalModalViewModel.tsx |
 | [Client API-Fetch Fields (useClientApiFields / apiFields.json)](features/client-api-fetch-fields.md) | The mechanism that resolves a client's **API-fetch projection** — which `fields` / `ojoin` / `join` / `where` to request from the TOGa API for a given page — fr | toga25-supply/src/fieldsConfig/resolveApiConfig.ts, toga25-supply/src/fieldsConfig/useClientApiFields.ts, toga25-supply/src/fieldsConfig/index.ts, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/viewModel/FIELDS/apiFields.json, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/viewModel/useSalesOrderRecordModalLayoutModel.tsx, toga25-supply/src/layout/ItemRecordModalLayout/viewModel/FIELDS/apiFields.json, toga25-supply/src/layout/ItemRecordModalLayout/viewModel/useItemRecordModalViewModel.tsx |
 | [Client-Configurable Fields (useClientFields / fieldsConfig)](features/client-configurable-fields.md) | The mechanism for config that **varies by client** (or client × role) — field overrides, filter buttons, group-by options, column pickers, layout toggles — with | toga25-supply/src/fieldsConfig/index.ts, toga25-supply/src/fieldsConfig/useClientFields.ts, toga25-supply/src/pages/SalesOrders/viewModel/FIELDS/, toga25-supply/src/pages/Inventory/viewModel/FIELDS/, toga25-supply/src/pages/Inventory/README.md, toga25-supply/src/layout/ItemRecordModalLayout/viewModel/FIELDS/, toga25-supply/src/layout/VendorItemRecordModalLayout/viewModel/FIELDS/, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/sections/SalesOrderTopBar.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/viewModel/FIELDS/ |
@@ -13,7 +13,7 @@
 | [Side navigation & default route — an empty nav renders a BLANK PAGE and gets reported as "cannot log in"](features/side-navigation-and-default-route.md) | The 2.5 side nav is **100% backend-driven** by the `navigation` surface bundle, and the same list also decides **which routes exist** and **where `/` lands**. | toga25-supply/src/routes.tsx, toga25-supply/src/layout/AppLayout/viewModel/useAppLayoutViewModel.ts, api2/Component/Api/V2/V2.php, _underscore/Model/Core/Surface.php |
 | [SSO redirect & public-vs-user session gating (useAuthenticationFlow)](features/sso-redirect-and-session-gating.md) | How 2.5 Supply decides, on every navigation, whether an anonymous visitor should be bounced to their client's SSO IdP instead of the local `/login` form. | toga25-supply/src/hooks/useAuthenticationFlow.ts, toga25-supply/src/routes.tsx, toga25-supply/src/contexts/AuthContext.tsx, toga25-supply/src/api/api.ts |
 | [Surface Frontend (DB-driven UI consumption, src/surface/)](features/surface-frontend.md) | The frontend consumer of the platform-wide Surface layer — DB-driven UI config fetched from `GET /v2/surfaces/meta?slug=<slug>` instead of statically-imported J | toga25-supply/src/App.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/layoutComponents/DenialBanner.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/SalesOrderRecordModal.module.css, toga25-supply/src/pages/SalesOrders/view/SalesOrderApprovalModalsLayout/SalesOrderApprovalModalsLayout.tsx, toga25-supply/src/layout/RecordApprovalModal/RecordApprovalModalLayout.tsx, toga25-supply/src/layout/RecordApprovalModal/view/ApprovalTimelineView.tsx, toga25-supply/src/layout/RecordApprovalModal/ApprovalModal.module.css, toga25-supply/src/utils/formatDateTime.ts, toga25-supply/src/utils/index.ts, toga25-supply/src/surface/evaluateSurfaceRule.ts, toga25-supply/src/layout/RecordApprovalModal/, toga25-supply/src/contexts/AuthContext.tsx, toga25-supply/src/surface/applyColSpan.ts, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/helpers/sectionRenderers.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/helpers/getVisibleSections.ts, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/layoutComponents/SalesOrderApprovalSummaryGrid.tsx, toga25-supply/src/surface/useFetchSurfaceMeta.ts, toga25-supply/src/pages/SalesOrders/helpers/surfaceBundleToTenantFields.ts, toga25-supply/src/pages/ServiceRequests/view/ServiceRequestRecordModalLayout/ServiceRequestRecordModalLayout.tsx, toga25-supply/src/pages/ServiceRequests/view/ServiceRequestRecordModalLayout/view/ServiceRequestsView.tsx, toga25-supply/src/pages/ServiceRequests/view/ServiceRequestRecordModalLayout/viewModel/useServiceRequestRecordModalLayoutModel.tsx, toga25-supply/src/pages/ServiceRequests/view/ServiceRequestRecordModalLayout/viewModel/FIELDS/apiFields.json, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/sections/SalesOrderTopBar.tsx, toga25-supply/src/pages/SalesOrders/helpers/buildPatchedTenantFields.ts, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/viewModel/useSalesOrderRecordModalLayoutModel.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/SalesOrderView.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/layoutComponents/SalesOrderSummaryGrid.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/helpers/getDetailSections.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/sections/SalesOrderNotesSection.tsx, toga25-supply/src/pages/SalesOrders/helpers/cleanOrder.ts, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/sections/AdminNotesSection.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/helpers/getAdminNotes.ts, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/helpers/index.ts, toga25-supply/src/surface/evaluateSurfaceRule.ts, toga25-supply/src/surface/resolveElementState.ts, toga25-supply/src/pages/SalesOrders/helpers/evaluateEnableRule.ts, toga25-supply/src/pages/SalesOrders/hooks/useSalesOrderRowRecordState.ts, toga25-supply/src/surface/actionRegistry.ts, toga25-supply/src/surface/componentRegistry.tsx, toga25-supply/src/surface/SurfaceActionBar.tsx, toga25-supply/src/surface/SurfaceSection.tsx, toga25-supply/src/surface/resolve.ts, toga25-supply/src/surface/types.ts, toga25-supply/src/surface/index.ts, toga25-supply/src/pages/Login/LoginPage.tsx, toga25-supply/src/pages/SalesOrders/SalesOrders.tsx, toga25-supply/src/pages/SalesOrders/view/SurfaceRowActions.tsx, toga25-supply/src/pages/SalesOrders/hooks/useSalesOrderVip.ts, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/sections/SalesOrderTopBar.tsx, toga25-supply/src/pages/Items/ItemsPage.tsx, toga25-supply/src/pages/Items/viewModel/useItemsPageViewModel.tsx, toga25-supply/src/pages/VendorItems/VendorItemsPage.tsx, toga25-supply/src/pages/VendorItems/viewModel/useVendorItemsPageViewModel.tsx, toga25-supply/src/pages/Inventory/Inventory.tsx, toga25-supply/src/pages/Inventory/viewModel/useInventoryPageViewModel.tsx, toga25-supply/src/pages/Inventory/viewModel/FIELDS/index.ts, toga25-supply/src/fieldsConfig/index.ts, toga25-supply/src/layout/ItemRecordModalLayout/helpers/surfaceBundleToItemFields.ts, toga25-supply/src/layout/ItemRecordModalLayout/helpers/index.ts, toga25-supply/src/layout/ItemRecordModalLayout/viewModel/useItemRecordModalViewModel.tsx, toga25-supply/src/layout/ItemRecordModalLayout/ItemRecordModalLayout.tsx, toga25-supply/src/layout/ItemRecordModalLayout/components/ItemRecordView.tsx, toga25-supply/src/surface/useStatusColors.ts, toga25-supply/src/surface/SurfaceHeader.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderApprovalModalsLayout/helpers/surfaceBundlesToDecisionFields.ts, toga25-supply/src/pages/SalesOrders/view/SalesOrderApprovalModalsLayout/viewModel/useApprovalModalViewModel.tsx |
-| [Talos Integration (AppLayout host + adapter wiring)](features/talos-integration.md) | toga25-supply is the first host of the shared blox [Talos assistant](../../toga-blox/features/talos-assistant.md). | toga25-supply/src/layout/AppLayout/AppLayout.tsx, toga25-supply/src/components/Header/Header.tsx, toga25-supply/src/components/Header/Header.module.css, toga25-supply/src/index.css, toga25-supply/src/assets/talos-owl.png |
+| [Talos Integration (AppLayout host, live Aegra streaming, LangGraph→blox mapper)](features/talos-integration.md) | toga25-supply is the first host of the shared blox [Talos assistant](../../toga-blox/features/talos-assistant.md). | toga25-supply/src/api/talos.ts, toga25-supply/src/hooks/useTalosSession.ts, toga25-supply/src/providers/TalosStreamProvider.tsx, toga25-supply/src/utils/talosMessages.ts, toga25-supply/src/utils/talosMessages.test.ts, toga25-supply/src/layout/AppLayout/AppLayout.tsx, toga25-supply/src/components/Header/Header.tsx, toga25-supply/src/components/Header/Header.module.css, toga25-supply/src/index.css, toga25-supply/src/assets/talos-owl.png |
 | [Transfer Orders page (TableView → Core surfaces → React page + record modal)](features/transfer-orders-page.md) | The Transfer Orders screen — list + read-only record modal — built end to end on 2026-08-28 from a Claude Design prototype. | toga25-supply/src/pages/TransferOrders/TransferOrders.tsx, toga25-supply/src/pages/TransferOrders/hooks/useTransferOrdersTableState.ts, toga25-supply/src/pages/TransferOrders/viewModel/useTransferOrdersPageViewModel.tsx, toga25-supply/src/pages/TransferOrders/view/TransferOrdersTableLayout/TransferOrdersTableLayout.tsx, toga25-supply/src/pages/TransferOrders/view/TransferOrderRecordModalLayout/TransferOrderRecordModalLayout.tsx, toga25-supply/src/pages/TransferOrders/view/TransferOrderRecordModalLayout/hooks/useTransferOrderRecord.ts, toga25-supply/src/pages/TransferOrders/view/TransferOrderRecordModalLayout/viewModel/useTransferOrderRecordModalLayoutModel.ts, toga25-supply/src/pages/TransferOrders/view/TransferOrderRecordModalLayout/view/TransferOrderRecordView.tsx, toga25-supply/src/pages/TransferOrders/view/CreateTransferOrderModal/CreateTransferOrderModal.tsx, toga25-supply/src/pages/TransferOrders/view/CreateTransferOrderModal/index.ts, toga25-supply/src/pages/TransferOrders/view/CreateTransferOrderModal/hooks/usePurchaseOrderItemRows.ts, toga25-supply/src/pages/TransferOrders/view/CreateTransferOrderModal/hooks/useTargetLocationOptions.ts, toga25-supply/src/pages/TransferOrders/view/CreateTransferOrderModal/hooks/useTransferSourceLocation.ts, toga25-supply/src/pages/TransferOrders/view/CreateTransferOrderModal/hooks/useLocationContacts.ts, toga25-supply/src/pages/TransferOrders/view/CreateTransferOrderModal/hooks/useCreateLocationContact.ts, toga25-supply/src/pages/TransferOrders/view/CreateTransferOrderModal/view/AddContactModal.tsx, toga25-supply/src/pages/TransferOrders/view/CreateTransferOrderModal/view/TransferNotesField.tsx, dbchanges2/Client/2026-09-01a - PurchaseOrderItemQtyFieldsApiRoleRead.sql, toga25-supply/src/surface/useColumnVisibilityModalConfig.ts, toga25-supply/src/routes.tsx, dbchanges2/Core/2026-08-28a - TransferOrderSurfaceSeed.sql, dbchanges2/Core/2026-08-28b - TransferOrderListActionsSurfaceSeed.sql, dbchanges2/Client/2026-08-28a - TransferOrderStageThemeTokens.sql, dbchanges2/Client/2026-08-28b - TransferOrderItemsTimestamps.sql, dbchanges2/Client_Nychh/2026-08-28a - TransferOrdersTableView.sql, dbchanges2/Client_Nychh/2026-08-28b - TransferOrdersNavigationEnable.sql, dbchanges2/Client_Nychh/2026-08-28c - TransferOrderRecordAcl.sql |
 | [AWS Amplify Multi-Environment Deployment](workflows/amplify-deployment.md) | How `toga25-supply` deploys to **all** of its environments on AWS Amplify from a **single shared `amplify.yml`**. | toga25-supply/amplify.yml, toga25-supply/src/api/api.ts, toga25-supply/src/hooks/useAuthenticationFlow.ts, toga25-supply/vite.config.ts, toga25-supply/package.json, toga25-supply/.env.development |
 | [Cypress Testing Harness (component + e2e)](workflows/cypress-testing.md) | The Cypress test harness for the `toga25-supply` frontend, bootstrapped from scratch (`cypress` was already a dependency but there was no config, no `cypress/` | toga25-supply/cypress.config.ts, toga25-supply/cypress/tsconfig.json, toga25-supply/cypress/support/component.tsx, toga25-supply/cypress/support/component-index.html, toga25-supply/cypress/support/e2e.ts, toga25-supply/cypress/support/commands.ts, toga25-supply/cypress/support/fixtures.ts, toga25-supply/cypress/support/mocks/useApprovalModalViewModel.ts, toga25-supply/cypress/component/SalesOrderApprovalModalsLayout.cy.tsx, toga25-supply/cypress/component/RecordApprovalModalLayout.cy.tsx, toga25-supply/cypress/component/EnterPoNumberModal.cy.tsx, toga25-supply/cypress/e2e/salesOrderApproval.cy.ts |

package/knowledge/2.0/apps/toga25-supply/architecture.md

@@ -17,7 +17,9 @@ files:
   - toga25-supply/src/layout/
   - toga25-supply/src/pages/
   - toga25-supply/src/hooks/useTableCellInteractions.ts
+  - toga25-supply/src/providers/TalosStreamProvider.tsx
 related:
+  - features/talos-integration.md
   - features/client-configurable-fields.md
   - features/meta-driven-table-data.md
   - features/column-visibility.md
@@ -118,5 +120,14 @@ its primary consumer and resolves it via a symlinked `node_modules/@agilant/toga
   can serve a persisted entry from a **previous session** and never fetch — the symptom is an empty
   list/dropdown with **nothing in the network tab**, which reads as a backend fault and is not one.
   (`staleTime: Infinity` on the **surface-meta** hooks is a deliberate, separate exception.)
-- **Typecheck with `npx tsc --noEmit` / `npx tsc -b`** after changes; adding a required key to
-  `ClientFields` surfaces every bundle missing it.
+- **⚠ `npx tsc --noEmit` at the repo root checks NOTHING — it is a silent no-op.** Verified
+  2026-09-01: the root `tsconfig.json` is references-only (`files: []`), so it compiles nothing
+  and **always exits 0**, reporting success on a codebase full of type errors.
+  **Always type-check with `npx tsc --noEmit -p tsconfig.app.json`** (or `npx tsc -b`, which
+  walks the references). Adding a required key to `ClientFields` then surfaces every bundle
+  missing it. The identical trap is documented for `toga2-view`
+  ([architecture](../toga2-view/architecture.md)); **any app sharing this tsconfig shape (likely
+  `toga25-desk`) is probably affected too — verify before asserting it.**
+- **Talos streaming lives in `src/providers/TalosStreamProvider.tsx`, above the router outlet.**
+  `AppLayout` wraps `AppLayoutInner` so it can consume the provider it renders. See
+  [talos-integration](features/talos-integration.md).

package/knowledge/2.0/apps/toga25-supply/features/talos-integration.md

@@ -1,14 +1,19 @@
 ---
-title: Talos Integration (AppLayout host + adapter wiring)
+title: Talos Integration (AppLayout host, live Aegra streaming, LangGraph→blox mapper)
 framework: "2.0"
 repo: toga25-supply
 project: TOGa 2.5 Supply
 client: shared
 type: feature
 status: active
-updated: 2026-08-28
+updated: 2026-09-01
 owners: [apeterson]
 files:
+  - toga25-supply/src/api/talos.ts
+  - toga25-supply/src/hooks/useTalosSession.ts
+  - toga25-supply/src/providers/TalosStreamProvider.tsx
+  - toga25-supply/src/utils/talosMessages.ts
+  - toga25-supply/src/utils/talosMessages.test.ts
   - toga25-supply/src/layout/AppLayout/AppLayout.tsx
   - toga25-supply/src/components/Header/Header.tsx
   - toga25-supply/src/components/Header/Header.module.css
@@ -16,132 +21,206 @@ files:
   - toga25-supply/src/assets/talos-owl.png
 related:
   - ../../toga-blox/features/talos-assistant.md
+  - ../../toga-blox/workflows/local-link-into-a-consumer-app.md
   - ../../talos/features/chat-frontend.md
+  - ../../talos/features/aegra-api.md
   - ../../../standards/frontend.md
 ---
 
 ## Summary
 
 toga25-supply is the first host of the shared blox [Talos assistant](../../toga-blox/features/talos-assistant.md).
-**Enabled for ALL clients (no per-client gating).** `AppLayout` is the host: it owns Talos
-state and injects the adapter; the launcher renders in the header, the panel at app root.
-(TRUE-80693)
+**Enabled for ALL clients (no per-client gating).** `AppLayout` is the host: the launcher renders
+in the header, the panel at app root.
+
+As of **2026-09-01 the live Aegra/LangGraph streaming backend is BUILT** (TRUE-80693). `onSend` is
+no longer a stub — the panel runs in blox's new **controlled mode** and the stream lives in a
+supply-owned provider. All LangChain code is **app-local**; blox stays pure UI.
 
 ## How it works
 
-- **AppLayout owns the state** — `open` / `expanded` / `width` / `dockWidth` — and injects the
-  adapter:
-  - `onSend`: **still the stub.** The live streaming backend is designed but unbuilt — see
-    *Real streaming backend* below.
-  - `onOpenRecord(id)` → navigate `/sales-orders?sales-orders=<id>`.
-  - `onAction("approvals")` → navigate `/sales-orders`.
-  - `onDockWidthChange(px)` → reserve layout width for the docked panel.
-- **Rendering** — `<TalosLauncher>` renders in the header via a new presentational
-  `talosLauncher` slot prop on the blox `Header` component, laid out through a `.headerActions`
-  flex wrapper. `<TalosPanel>` renders at app root.
-- **Branding/font** — the owl asset (`src/assets/talos-owl.png`) is passed as
-  `branding.avatarSrc`; Plus Jakarta Sans is loaded in `src/index.css` (the shared component
-  does not import fonts itself).
+```
+src/api/talos.ts                        — sole VITE_TALOS_API read chokepoint + assistants lookup
+src/hooks/useTalosSession.ts            — resolves token + assistantId → a `connection` state
+src/providers/TalosStreamProvider.tsx   — the single useStream() call, exposed via own context
+src/utils/talosMessages.ts              — LangGraph Message[] → blox TalosMessageModel[]
+src/layout/AppLayout/AppLayout.tsx      — host: provider wrapper + controlled panel props
+```
 
-## Gotcha — reserve dock width on the OUTER wrapper, not just `<main>`
+### `src/api/talos.ts` — the env chokepoint
 
-The docked panel is `position: fixed`, full-height on the right. The blox `Header` is in
-**normal document flow** (NOT fixed). Reserving the dock width only on `<main>` leaves the
-header's right edge sitting **under** the panel, hiding the launcher + avatar. **Fix:** apply
-the reserved dock width (`marginRight` = the `onDockWidthChange` value) to the **outer app
-wrapper** so the header shifts along with the content.
+The only place `VITE_TALOS_API` is read. Exposes `getTalosApiUrl()`, `isTalosConfigured()`,
+`fetchTalosAssistants()`, `pickTalosAssistant()`.
 
-## Real streaming backend — design (DECIDED 2026-08-28, NOT yet implemented)
+`fetchTalosAssistants()` **logs the HTTP status before throwing** — `401` = token/issuer mismatch,
+`403` = tenant not provisioned. Without that log React Query reduces both to a silent boolean and
+you debug blind.
 
-`onSend` is still the stub. The plan below replaces it with the live Aegra/LangGraph backend,
-copying the proven approach in [TOGa IQ's chat front-end](../../talos/features/chat-frontend.md).
-No code has been written yet.
+**Do NOT send a body or a `Content-Type` on the `GET /assistants` call.** `fetch` forbids a body on
+GET, and a JSON content-type only adds a CORS preflight. (The curl example circulated internally
+used `--data '{}'`; do not copy it into the browser client.)
 
-### Package choice: `@langchain/langgraph-sdk/react`, app-local
+### `assistantId` is PER-TENANT — fetch it, never pin it in env
 
-- **Use `useStream` from `@langchain/langgraph-sdk/react`** — the same import talos uses — **not
-  `@langchain/react`.** Reasons: one fewer peer (`@langchain/react` additionally needs
-  `@langchain/core ^1.1.48`); the path is already proven in-house so
-  `talos/src/providers/Stream.tsx` can be lifted nearly verbatim; and `@langchain/react`'s extra
-  surface is largely **media hooks/players** that blox has no components to render.
-- **Take only `useStream` for v1.** Add `useToolCalls` when tool activity is actually shown, and the
-  headless interrupt helpers when doing human-in-the-loop — *that* is where `@langchain/react` earns
-  its keep, so revisit it then, not now.
-- **Write our own context provider** (as talos does) rather than the library's `StreamProvider` —
-  supply-specific token / tenant / `threadId` / Aegra URL must be injected.
-- **It stays in supply, never in blox.** Per [frontend.md §21](../../../standards/frontend.md) this
-  is n=1, and per §13(b) a blox peer would force `@langchain/core` on all five consumer apps. blox
-  keeps `TalosPanel` as pure UI.
+`GET {aegra}/assistants?limit=100&offset=0` with the bearer returns:
+
+```jsonc
+{ "assistants": [ { "assistant_id": "…", "name": "…", "graph_id": "…",
+    "metadata": { "customer_facing": true, "read_only": true, "tenant_slug": "…" } } ],
+  "total": 1 }
+```
 
-### Why a provider at all — three jobs
+NYCHH returns exactly one — name `TOGa Supply`, `graph_id: deep_agent`, `read_only: true`,
+`customer_facing: true`.
 
-1. **Singleton.** `useStream` is stateful; two call sites = two independent conversations.
-2. **Survive route changes.** The panel is docked in `AppLayout` while the user navigates. If the
-   stream lived inside the panel, any unmount would kill an in-flight response and lose history — so
-   it must sit **above the router outlet**.
-3. **Be the app↔blox boundary.** Supply's token/tenant/`threadId`/Aegra URL enter here and LangGraph
-   message shapes are translated here, keeping `TalosPanel` app-agnostic and reusable by desk and
-   commerce later.
+**Selection rule (`pickTalosAssistant`):** prefer `metadata.customer_facing === true`; else fall
+back to the full list; take the first; `console.warn` when there is more than one candidate.
+Never silently pick, never throw.
 
-### Planned shape
+**Design consequence:** `useStream` takes **both** the token and `assistantId` as *values*, so there
+are now **two** async prerequisites that must resolve above the hook. That is why the panel's
+`connection` prop is load-bearing rather than polish.
 
+### `useTalosSession()` — the gate
+
+Returns `connection: "disabled" | "connecting" | "ready" | "error"` plus the token and assistantId.
+
+- **Gate on `isAuthenticated` (the `"user"` key), NOT on the presence of an accessToken.** blox
+  `fetchPublicToken` leaves a **public** token in storage for logged-out visitors, so "there is a
+  token" is not "there is a user."
+- **Key the assistants query by USER UUID, never by the token.** Supply persists the React Query
+  cache to `localStorage` (`supply-chain-query-cache`), so a token in a query key gets written to
+  disk.
+- `staleTime: Infinity`, `gcTime: Infinity`, `retry: false`.
+- **Anti-pattern — do not gate with `useSuspenseQuery`/Suspense.** It suspends the subtree, so the
+  panel **unmounts and remounts** — flashing and dropping whatever the user typed in the composer.
+  Keep it a plain query and gate on the returned `connection`.
+
+### `TalosStreamProvider` — outer gate + inner session
+
+One `useStream` call from `@langchain/langgraph-sdk/react`, exposed through a supply-owned context.
+`threadId` lives in the URL via react-router `useSearchParams` (**never `nuqs`** — Next-only).
+
+It is deliberately **split in two**: an outer gate component and an inner `TalosStreamSession`.
+Hooks cannot be called conditionally, and the stream must not mount until the token *and* the
+assistantId are real values — so the gate renders the session only once both resolve.
+
+Why a provider at all: `useStream` is stateful (two call sites = two conversations), it must sit
+**above the router outlet** so navigation does not kill an in-flight response, and it is the
+app↔blox boundary where LangGraph shapes are translated.
+
+### `AppLayout` — split into `AppLayoutInner`
+
+`AppLayout` now wraps `AppLayoutInner` in `TalosStreamProvider`, **because a component cannot
+consume a provider it renders**. The panel is driven by the controlled props
+(`messages` / `isStreaming` / `onSubmit` / `onStop` / `connection`); the adapter now carries only
+navigation side effects (`onOpenRecord` → `/sales-orders?sales-orders=<id>`, `onAction("approvals")`
+→ `/sales-orders`, `onDockWidthChange` → reserve layout width).
+
+**Maps the app-only `"disabled"` state to `"error"`** when passing `connection` down — blox has no
+`"disabled"` value.
+
+### `talosMessages.ts` — the LangGraph → blox mapper
+
+- Handles LangGraph's **string-OR-content-blocks** union for `content`.
+- Filters to `human` / `ai` only — `system`, `tool` and `remove` are dropped.
+- An **empty AI turn becomes `{ thinking: true }`** (the stream opening). An empty human turn is
+  dropped.
+- Streamed text goes to **`message`** (light markdown), *not* `paras`: during a stream the text is
+  partial, and splitting it into finished paragraphs reflows the bubble on every token.
+- **Deliberate loss:** tool calls and HITL interrupts have **no representation** in
+  `TalosMessageModel` and are dropped. Surfacing them needs new blox props — not a mapper change.
+
+13 unit tests in `src/utils/talosMessages.test.ts`.
+
+## Gotcha — user turns use `text`, Talos turns use `message`/`paras`
+
+blox `TalosMessage` renders **`message.text` for a `role: "user"` turn** but
+**`message.message` / `message.paras` for a `role: "talos"` turn**. The mapper originally put user
+turns in `message`, which renders an **empty bubble**. Caught only by writing the tests.
+
+```ts
+// CORRECT
+{ role: "user",  text }       // user turn
+{ role: "talos", message }    // assistant turn
 ```
-src/api/talos.ts                                    — sole VITE_TALOS_API read chokepoint + token exchange
-src/providers/TalosStreamProvider.tsx               — the single useStream call, exposed via context
-src/layout/AppLayout/viewModel/useTalosViewModel.ts — flat shape for the panel
-```
 
-- **The mapper is where the estimate lives.** LangGraph `Message[]` → blox `TalosMessageModel[]` do
-  **not** line up: `type: "ai" | "human"` vs `role: "talos" | "user"`; streamed content blocks vs a
-  finished `paras: string[]`; and tool calls and interrupts have **no representation at all** in
-  blox's model. This is the same gap that forces the `TRUE-80692` contract change.
-- **`threadId` in URL search params via react-router 7 `useSearchParams`** — **not `nuqs`**, which is
-  Next-only. Do not copy that part of talos's provider (§5, URL as source of truth).
-- **Token held in React Query** per [frontend.md §3](../../../standards/frontend.md) — fetched server
-  state, never Zustand.
-- **Tear down token + `threadId` + conversation on logout and tenant switch** per §18.
-
-### Async auth gating — and the anti-pattern
-
-`useStream` takes the token as a **value** (`defaultHeaders`), not a promise, so you **cannot await
-it inside the hook**. That single constraint decides the design:
-
-- Awaiting the token inside `onSend` (via `queryClient.ensureQueryData`, reusing the panel's existing
-  thinking/error states, lazily fetching on first send) works **only** for the non-streaming one-shot
-  contract.
-- For **streaming**, the gate must sit **above** the hook — do not mount the stream until the token
-  query resolves. This is exactly why the panel's `connection` prop stops being optional polish and
-  becomes required.
-
-**Anti-pattern — do not use `useSuspenseQuery`/Suspense for this gate.** It suspends the subtree, so
-the panel **unmounts and remounts** — flashing and dropping whatever the user typed in the composer —
-and in a shared library the thrown promise surfaces in host apps that never opted into a boundary.
-Keep it a plain query.
-
-**Open product decision:** mid-stream 401 behavior — silent refresh and resume, vs. surface an error
-and let the user resend. Decide deliberately rather than discovering it in QA.
-
-## Aegra-side blockers — backend config, zero front-end code
-
-Each of these masquerades as a front-end bug. **Confirm them with the Aegra owners
-(`akhokhani`, `jcardinal`) BEFORE building the provider** — answer (c) especially decides whether the
-auth/loading layer gets built at all.
-
-- **(a) CORS allowlist** must include supply's **per-client hostnames** (nychh, compass, quad, …).
-  The symptom is a request that never leaves the browser — no response to debug. Note the browser
-  calls Aegra **directly** cross-origin (proven by talos), and a static Amplify SPA has no server
-  route handler to proxy through, so this is unavoidable. Related: Aegra also validates the
-  requesting domain against a `Domains` table, and `Origin` is a forbidden header a browser cannot
-  set — so a new origin needs its **own `Domains` row**.
-- **(b) Tenant provisioning is explicit, with no auto-create.** An unregistered org gets a clean
-  **403 on every call even with a valid token** (control-plane DB / `tenant_router` LRU — see
-  [talos architecture](../../talos/architecture.md)).
-- **(c) Token audience.** Aegra `AUTH_TYPE=togahub` validates api2 JWTs, but supply's token is issued
-  for the **supply** client, not TogaHub. Either Aegra accepts it (trivial) or supply needs a
-  handoff — api2 already exposes `/auth/delegator`, `/auth/encrypted`, and
-  `/auth/encrypted-user-uuid` for exactly this cross-app identity pass.
+Anyone writing to `TalosMessageModel` by hand will hit this.
+
+## Gotcha — reserve dock width on the OUTER wrapper, not just `<main>`
+
+The docked panel is `position: fixed`, full-height on the right. The blox `Header` is in **normal
+document flow** (NOT fixed). Reserving the dock width only on `<main>` leaves the header's right
+edge sitting **under** the panel, hiding the launcher + avatar. **Fix:** apply the reserved dock
+width (`marginRight` = the `onDockWidthChange` value) to the **outer app wrapper**.
+
+## Gotcha — `npm install` silently un-links blox and Talos disappears
+
+Any `npm install` in this repo replaces the `node_modules/@agilant/toga-blox` **symlink** with the
+registry version, which contains no Talos. The symptom looks nothing like a dependency problem.
+Full symptom + relink recipe:
+[Local-linking blox into a consumer app §1a](../../toga-blox/workflows/local-link-into-a-consumer-app.md).
+
+## Environment config
+
+`VITE_TALOS_API` is set to `https://api.beta.togaiq.com` in **7 non-prod env files**. It is left
+**commented out in `.env` (production)** because no live production Aegra host is confirmed —
+`isTalosConfigured()` therefore returns false there and `connection` resolves to `"disabled"`.
+
+## Package choice: `@langchain/langgraph-sdk/react`, app-local
+
+- **`useStream` from `@langchain/langgraph-sdk/react`** — the same import talos uses — **not
+  `@langchain/react`.** The decision stands: the path is proven in-house so
+  `talos/src/providers/Stream.tsx` lifts nearly verbatim, and `@langchain/react`'s extra surface is
+  largely **media hooks/players** blox has no components to render.
+- **⚠ Correction (verified 2026-09-01): the old "one fewer peer" reason was WRONG.**
+  `@langchain/langgraph-sdk@1.10.0` declares `@langchain/core: ^1.1.48` as a **required
+  (non-optional) peer** itself; `react`/`react-dom` are the optional ones. Symptom when it is
+  missing: Vite/esbuild dep-optimize **hard-fails** with `Could not resolve
+  "@langchain/core/messages"` and the dev server exits. Install `@langchain/core` alongside the SDK.
+- **Take only `useStream` for v1.** Add `useToolCalls` when tool activity is actually shown, and the
+  headless interrupt helpers for human-in-the-loop — that is when `@langchain/react` earns its keep.
+- **It stays in supply, never in blox.** Per [frontend.md §21](../../../standards/frontend.md) this
+  is n=1, and per §13(b) a blox peer would force `@langchain/core` on all five consumer apps.
+
+**Still open:** mid-stream 401 behavior — silent refresh and resume vs. surface an error and let the
+user resend. Decide deliberately rather than discovering it in QA.
+
+## Aegra-side status (was "three blockers")
+
+- **(a) CORS — NARROWED, still open.** The old worry that Aegra's `Domains` gate needs a spoofed
+  `Origin` (talos pins `Origin: http://talos` server-side, and `Origin` is a forbidden header) is
+  **moot for supply**: supply's real browser origin *is* the registered hostname, so the browser
+  sets it correctly for free. What **is** still a blocker: **Aegra returns CORS headers on the
+  OPTIONS preflight only, not on the actual response** — verified 2026-09-01 from both
+  `http://nychh.dev.sandbox.togasupply:5173` and `https://nychh.togasupply.com`
+  (`access-control-allow-origin: *` on the preflight, **no** `access-control-*` header on the real
+  GET). The browser will block every real response until this is fixed. Reported to `akhokhani`.
+- **(b) Tenant provisioning is explicit, no auto-create.** Unchanged — an unregistered org gets a
+  clean **403 on every call even with a valid token**.
+- **(c) Token audience — RESOLVED, and it is the good outcome.** Aegra `AUTH_TYPE=togahub`
+  **accepts a supply-issued api2 JWT.** Proven by a working `GET /assistants` whose bearer carried
+  `aud` = a **supply** hostname (`https://nychh.togasupply.com`), `iss`/`sub` =
+  `http://api.beta.togahub.com`, `id.client.slug: Nychh`, 3600s life. Answer from `akhokhani`.
+  **Consequence: no token exchange, no `/auth/delegator` handoff, no auth-exchange layer.** Supply
+  passes the token it already has straight into `defaultHeaders`.
 
 ## Change history
+- 2026-09-01 — **BUILT the live streaming integration.** Added `src/api/talos.ts` (env chokepoint +
+  runtime `GET /assistants` lookup — `assistantId` is **per-tenant**, never pinned in env),
+  `useTalosSession` (gates on `isAuthenticated`, not on a token, because blox leaves a **public**
+  token in storage; assistants query keyed by user UUID because the query cache is persisted to
+  disk), `TalosStreamProvider` (one `useStream`, own context, `threadId` via react-router
+  `useSearchParams`, split into outer gate + inner session because hooks can't be conditional), the
+  LangGraph→blox mapper, and `AppLayout` → `AppLayoutInner` (a component can't consume a provider it
+  renders). RESOLVED blocker (c): Aegra `AUTH_TYPE=togahub` accepts a **supply-issued** api2 JWT
+  (`aud` = a supply hostname), so there is no token exchange. Narrowed blocker (a): the `Origin`
+  spoof worry is moot for supply, but Aegra sends CORS headers **on the preflight only**, so real
+  responses are still browser-blocked. FIXED a real bug found by the new tests: blox renders
+  `text` for user turns and `message`/`paras` for Talos turns — the mapper's original shape rendered
+  an empty user bubble. CORRECTED the recorded package rationale: `@langchain/langgraph-sdk`
+  **does** require `@langchain/core ^1.1.48` as a peer, so "one fewer peer" was wrong (the decision
+  stands for other reasons). (apeterson)
 - 2026-08-28 — Design/research only, no code: chose `useStream` from
   `@langchain/langgraph-sdk/react` (not `@langchain/react`), kept **app-local** rather than in blox
   (frontend.md §13b/§21), and designed a route-surviving singleton `TalosStreamProvider` above the

package/knowledge/2.0/standards/frontend.md

@@ -5,7 +5,7 @@ project: _Underscore
 client: shared
 type: standard
 status: active
-updated: 2026-08-27
+updated: 2026-09-01
 owners: [jcardinal, apeterson]
 files: []
 related:
@@ -122,6 +122,22 @@ ship the **identical** app-config flag set — the two files differ only in whit
 `resolve.alias`). A path alias that exists in only one of the two type-checks-but-won't-build (or
 the reverse). Keep them in lockstep.
 
+**MUST: type-check with `-p tsconfig.app.json` (or `tsc -b`) — never bare `npx tsc --noEmit`.**
+Because the root `tsconfig.json` is references-only (`files: []`), a bare root `tsc --noEmit`
+compiles nothing and **always exits 0**. It reports a clean build on a repo full of type errors,
+which makes it a false green in any pre-commit or CI-style check.
+
+```bash
+npx tsc --noEmit -p tsconfig.app.json    # ✅
+npx tsc --noEmit                         # ❌ silent no-op
+```
+
+Documented independently in two repos on this tsconfig shape — `toga25-supply` (verified
+2026-09-01) and `toga2-view` ([architecture](../apps/toga2-view/architecture.md)) — so assume it
+for any app sharing the shape, but **verify per repo before asserting it**. Note also that a repo
+may carry **pre-existing** errors under the app config (toga2-view does), in which case the pass
+criterion is "no *new* errors vs. a stashed baseline", not zero.
+
 ## 3. State management doctrine — **MUST** (high-value)
 
 There are exactly **three homes** for state, and they do not overlap. Verified 2026-08-18 across
@@ -664,6 +680,11 @@ consuming app, guard against them and move on.
 
 ## Change history
 
+- 2026-09-01 — §2: added a MUST to **type-check with `-p tsconfig.app.json` (or `tsc -b`), never
+  bare `npx tsc --noEmit`** — the root `tsconfig.json` is references-only (`files: []`), so a bare
+  root run compiles nothing and always exits 0, a false green in any pre-commit/CI check. Verified
+  in `toga25-supply` 2026-09-01 and already documented for `toga2-view`; assume it for any app on
+  this tsconfig shape but verify per repo. (apeterson)
 - 2026-08-27 — §13(a): corrected the caret rationale — a caret on a **prerelease is inert**, not
   floating; the real floating risk is `toga2-commerce`'s `amplify.yml` overwriting the manifest pin
   at build time. §22: added three blox auth gotchas found debugging toga25-supply SSO

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

@@ -196,4 +196,12 @@ to but distinct from Compass USA. Like Compass USA it spans the **2.0** commerce
   numbers — because it does **not** use NetSuite, so it never hit the inventory-adjustment
   dupe-item bug that fed the merge. The catalog-fold damage and reversal were Compass USA only.
   See [Compass USA catalog-fold reversal](../compass-usa/workflows/catalog-fold-reversal.md).
+- **Items listing being filtered to catalog 1 (written 2026-09-01, NOT yet applied).** A migration
+  sets `TableViews.apiWhereClause = '(Items.catalogId:eq:1)'` on `Client_CompassCanada`'s shared
+  `items` view (`slug = 'items'`, id 9, recordId 21), alongside the same change in `Client_Compass`
+  and `Client_Quad`. **Canada is the harmless case today** — Canada has a **single catalog**
+  ("compass", see the bullet above), so every `Client_CompassCanada.Items` row is already catalog 1 and so the filter changes nothing visible now; it only pins the listing so a
+  future non-catalog-1 item (e.g. anything a NetSuite-style sync creates) would silently not appear.
+  Mechanism: [TableView apiWhereClause row-filtering](../../2.0/apps/api2/features/tableview-apiwhereclause-row-filtering.md);
+  catalog background: [Compass item catalogs](../compass-usa/features/item-catalogs-and-duplicate-items.md).
 - Related: [Compass USA](../compass-usa/profile.md).

package/knowledge/clients/compass-usa/features/item-catalogs-and-duplicate-items.md

@@ -17,6 +17,7 @@ files:
   - worker/crons/toga2/compass/workflow/1_transmit_compass_sales_orders_to_mits.php
 related:
   - odp-edi-850-item-resolution.md
+  - ../../../2.0/apps/api2/features/tableview-apiwhereclause-row-filtering.md
   - mits-po-to-so-item-linking.md
   - mits-sales-order-transmission-alerting.md
   - isfulfillable-data-quality-and-type-rule.md
@@ -132,6 +133,32 @@ Plus `-1` / `-2` suffixed copies: items **2431, 2432, 2443, 2653**.
   (e.g. the `#B1H` / `-S` variant forms above) or genuinely-shared ones before treating table-wide
   `partNumber` uniqueness as settled.
 
+## Filtering by catalog: fine for *display*, never for *resolution*
+
+The blanket rule below ("never scope a Compass item lookup to one catalog") is about **resolving a
+part number to a record** — order import, PO→SO linking, vendor-item matching. It does **not** mean
+a catalog filter is banned everywhere. A **listing** is the legitimate exception: showing a user
+only the customer-facing Compass catalog is a product decision, and nothing downstream re-resolves
+off that list.
+
+**In flight as of 2026-09-01 (SQL written, NOT yet applied):** the shared TOGa Supply `items` table
+view (`TableViews.slug = 'items'`, `id 9`, `recordId 21`) is being restricted to catalog 1 by
+setting `TableViews.apiWhereClause = '(Items.catalogId:eq:1)'` — one `UPDATE … WHERE slug = 'items'`
+per schema, in `Client_Compass`, `Client_CompassCanada` **and** `Client_Quad` (the same view exists
+with the same id/recordId in all three). No application code changes; the mechanism is
+[TableView row-filtering via apiWhereClause](../../../2.0/apps/api2/features/tableview-apiwhereclause-row-filtering.md).
+The migration was written as a loose `items_tableview_catalog_filter_2026-09-01.sql` in the
+workspace root and handed to a developer to run (the DB tooling is read-only) — it still needs to
+land in `dbchanges2/Client_<schema>/` under the mandatory `YYYY-MM-DD<letter> - Name.sql` filename
+before it is a real change-set.
+
+**Open decision on the clause, and it is the NULL question again.** `Items.catalogId` is nullable in
+all three schemas, so a bare `:eq:1` silently drops the NULL-catalog items (a real, non-trivial
+population here — see the gotcha below, and it is proportionally much larger in `Client_Quad`). If
+those items must stay visible in the listing, the clause has to be
+`(IFNULL(Items.catalogId,1):eq:1)` instead. Decide before applying; the two forms are not
+interchangeable.
+
 ## "Who changed this part number?" — the audit trail says nobody
 
 The reflex answer to a part number that looks edited is to hunt for the person who edited it. For
@@ -151,9 +178,10 @@ children" rule:
 
 ## Gotchas
 
-- **⚠ Never scope a Compass item lookup to one catalog** unless you have proved the item can only
-  come from that source. The correct default is `Items.partNumber IN (...)` with **no** catalog
-  condition, and then reference the resolved record **by `uuid`**. **The catalog filter never buys
+- **⚠ Never scope a Compass item *lookup* to one catalog** unless you have proved the item can only
+  come from that source. (A read-only **listing** filter is the one sanctioned exception — see
+  [Filtering by catalog](#filtering-by-catalog-fine-for-display-never-for-resolution) above.) The
+  correct default is `Items.partNumber IN (...)` with **no** catalog condition, and then reference the resolved record **by `uuid`**. **The catalog filter never buys
   uniqueness on Compass** — `Items.partNumber` is unique across the whole table (re-verified prod
   2026-09-01) — so every catalog condition is pure downside.
 - **⚠ The 2.0 side hardcodes the OTHER catalog, and it broke MR purchase orders.**
@@ -193,6 +221,14 @@ children" rule:
   **unresolved tension**: that reversal folded/restored 199 catalog-1 items by `UPPER(partNumber)`,
   which implies shared cross-catalog part numbers pre-merge and does not square with the same-day
   "partNumber is unique table-wide" verification — needs a prod re-check. (jcardinal)
+- 2026-09-01 — Split the catalog-filter rule into **display vs. resolution**: the "never scope to one
+  catalog" ban covers part-number *resolution*, while a read-only *listing* filter is sanctioned.
+  Recorded the in-flight (written, **not yet applied**) change setting
+  `TableViews.apiWhereClause = '(Items.catalogId:eq:1)'` on the shared `items` view
+  (`slug = 'items'`, id 9, recordId 21) in `Client_Compass`, `Client_CompassCanada` and
+  `Client_Quad`, and the open decision it carries: `Items.catalogId` is nullable, so bare `:eq:1`
+  hides NULL-catalog items and `IFNULL(Items.catalogId,1):eq:1` is the alternative. Migration still
+  needs moving into `dbchanges2/Client_<schema>/`. (bala)
 - 2026-09-01 — Recorded a **second, independent victim of the same catalog-scoping trap, on the 2.0
   side**: `_Model_Compass_PurchaseOrder::handleMrOrder` references MR sales-order items with a
   hardcoded `COMPASS_CATALOG_UUID` (`961dbcbc…` = catalog **1**), which is the mirror image of the

package/knowledge/clients/nychh/profile.md

@@ -12,6 +12,7 @@ apps:
   - worker
   - library
   - talos-backend
+  - talos
 project: _Underscore
 client: nychh
 type: profile

package/knowledge/clients/quad/profile.md

@@ -142,4 +142,16 @@ Client-specific DB change-sets live in `dbchanges2/Client_Quad/`.
   Quad's **storefront only** (not orders/transmit), and Quad was the **only other client besides
   Compass** that needed a reversal. See
   [Quad catalog-fold reversal](./workflows/catalog-fold-reversal.md).
+- **Items listing being filtered to catalog 1 (written 2026-09-01, NOT yet applied) — verify the
+  intent for Quad first.** A migration sets `TableViews.apiWhereClause = '(Items.catalogId:eq:1)'`
+  on `Client_Quad`'s shared `items` view (`slug = 'items'`, id 9, recordId 21); the same one-line
+  change is going to `Client_Compass` and `Client_CompassCanada`. Read it against the bullet above:
+  for Quad, catalog 1 is the **storefront (Etilize)** catalog and catalog 2 is the **procurement
+  (Agilant/NetSuite)** catalog that Quad's storefront orders actually sit on, so `:eq:1` hides the
+  procurement half of `Client_Quad.Items` from the Supply items listing — a much bigger cut than the
+  equivalent change on Compass, and a majority of Quad's items. `Items.catalogId` is also nullable
+  here and a bare `:eq:1` drops those rows too; `IFNULL(Items.catalogId,1):eq:1` recovers the NULLs
+  but not catalog 2. Mechanism:
+  [TableView apiWhereClause row-filtering](../../2.0/apps/api2/features/tableview-apiwhereclause-row-filtering.md);
+  catalog background: [Compass item catalogs](../compass-usa/features/item-catalogs-and-duplicate-items.md).
 - This profile is a starting point; expand as more Quad-specific behavior is captured.

package/package.json

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