toga-ai 1.0.903 → 1.0.905

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

@@ -29,6 +29,8 @@ Shared React+TS component/template/API library (`@agilant/toga-blox`) reused by
 
 `toga-blox` (npm package **`@agilant/toga-blox`**) is the shared React + TypeScript component / template / utility library reused across the 2.0 frontends: `toga2-view`, `toga2-supply`, `toga25-supply`, `toga2-commerce`, `toga2-hub`. Not a PHP framework repo — no `_underscore` backend. Filed under `2.0/` because every consumer is a 2.0 app, but structurally a standalone front-end package (`dependsOn: []`).
 
+**New-platform apps (toga25-desk, toga25-iq, toga2-template, future apps) do not use this repo — they use [toga25-blox](../toga25-blox/architecture.md), a source-shared (git, not npm) replacement.**
+
 Ships: presentational + data-aware **components** (`src/components/`), **templates** wiring components into ready screens (`src/templates/`, e.g. `PrimaryTable`, `Login`, `AddNotes`), a thin **API client** over axios + React Query (`src/api/`, `src/reactQuery/`), and **utilities** (`src/utils/`). Builds with `tsc` to `dist/` (not bundled), develops via Storybook, tests with Vitest.
 
 **Critical rules:**

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

@@ -13,10 +13,12 @@
 | [Client Fields — per-tenant / language / role content & config](features/client-fields.md) | Per-tenant/language/role JSON config that drives almost all commerce UI text, fields, and login fetches (Layer A global + Layer B FIELDS registry); open before |
 | [Config-Driven Expedited Shipping Gating (Cart)](features/expedited-shipping-gating.md) | Expedited shipping options are config-gated to show only when the cart holds a computer kit; open when touching cart shipping-method options or the gate config. |
 | [Filter / Search-Results Page & the Two Search Entry Points](features/filter-search-results-page.md) | Two search entry points (Home in-place vs Header→/filter) render the same card via different code paths and FIELDS files; open for any search-results or kit-car |
+| [Force Logout on Deployment (DeploymentGuard) — commerce](features/force-logout-on-deployment.md) | Signs every user out when a deploy bumps a Core parameter, after showing a notice; open for surprise logouts, a repeating "new version" toaster, or `useDeployme |
 | ["Order For" — header pill, delegated token switch, and the cart hand-off](features/header-order-for-dropdown.md) | Header pill that switches the session to a delegated token so a buyer orders **as** someone else; open before touching the pill, `useOrderForZu`, the delegation |
 | [Inactive-item purchase gating (standalone lines only — kits are exempt by design)](features/inactive-item-purchase-gating.md) | `Items.isActive = 0` blocks standalone purchase but means something different on kit components, so the gate keys on purchase CONTEXT not the flag; open when to |
 | [Multi-Tenant Resolution & Theming](features/multi-tenant-theming.md) | How the hostname resolves the tenant and fans out to API base URL, theme (CSS variables), and fields; open when adding a tenant or debugging wrong-theme/wrong-A |
 | [Order-submit sync sequencing (useSubmitOrder) — why these calls must not run in parallel](features/order-submit-sync-sequencing.md) | The item sync must finish before the header sync on order submit, or concurrent line deletes race a depth-3 response into an uncaught api2 500; open when touchi |
+| [Skeleton → content transitions (AnimatePresence mode, layout jump, blank gap)](features/page-loading-transitions.md) | How commerce swaps a loading skeleton for real content with framer-motion; open for page jump/flicker or a blank gap while loading. |
 | [Config-Driven Shipping Cost Waiver (Standard Ground free for computer kits)](features/shipping-cost-waiver-gating.md) | Config-driven cost waiver making Standard Ground free for a bare computer kit (Compass USA); open when touching shipping cost gates or the Compass free-freight |
 | [SSO sign-in, session gating & token refresh identity (hasSession / useClientSsoUrl)](features/sso-redirect-and-session-gating.md) | How commerce decides whether a visitor is signed in, shows the SSO panel or the credential form, and keeps a token refresh bound to one identity. |
 | [Storefront persona gating — the Home page's kit / category / item counts, and the persona switcher](features/storefront-persona-gating-and-home-counts.md) | What a storefront user sees on the Home page is decided **in the front end**, from `user._personaIds`, not by the API's ACL. |
@@ -24,4 +26,5 @@
 | [AWS Amplify Build & Deploy (non-prod environments)](workflows/amplify-build-and-deploy.md) | How toga2-commerce builds/deploys on AWS Amplify (one dynamic amplify.yml, branch-per-env, per-env blox channel); open to deploy, stand up an env, resolve a blo |
 | [Cart e2e — Cypress conventions & harness (toga2-commerce)](workflows/cypress-testing.md) | Cypress e2e conventions + the Cart harness (cartV2.cy.ts) for toga2-commerce; read before adding any spec here, and note it doubles as the config-cart refactor |
 | [Diagnosing ERR_HTTP2_PROTOCOL_ERROR (one client fails, everyone else is fine)](workflows/http2-protocol-error-diagnosis.md) | Diagnose ERR_HTTP2_PROTOCOL_ERROR when one client/network fails a togacommerce tenant but everyone else works (usually the client's TLS-inspection proxy, not ou |
+| [Running toga2-commerce locally (tenant hosts, not localhost)](workflows/local-development-hosts.md) | Commerce cannot run on `localhost`; use a tenant hostname in `/etc/hosts`. |
 | [Unit tests in toga2-commerce — vitest harness & the build-mode trap](workflows/unit-testing-vitest.md) | How to run and write unit tests in commerce (vitest + jsdom), and how to verify a change actually compiles without tripping the build-mode trap. |

package/knowledge/2.0/apps/toga2-commerce/features/force-logout-on-deployment.md

@@ -0,0 +1,46 @@
+---
+title: Force Logout on Deployment (DeploymentGuard) — commerce
+framework: "2.0"
+repo: toga2-commerce
+project: TOGa Commerce
+client: shared
+type: feature
+status: active
+updated: 2026-09-25
+owners: [apeterson]
+files:
+  - toga2-commerce/src/hooks/useDeploymentGuard.tsx
+  - toga2-commerce/src/lib/deploymentVersion.ts
+  - toga2-commerce/src/components/AuthLayout/AuthLayout.tsx
+  - toga2-commerce/src/contexts/AuthContext.tsx
+  - toga2-commerce/src/lib/authStorage.ts
+related:
+  - ./sso-redirect-and-session-gating.md
+  - ./catalog-cache-freshness.md
+  - ../../toga25-supply/features/force-logout-on-deployment.md
+---
+
+Signs every user out when a deploy bumps a Core parameter, after showing a notice; open for surprise logouts, a repeating "new version" toaster, or `useDeploymentGuard`.
+
+## Summary
+
+Core parameter `META_LAST_REFRESH_DATETIME` is polled while signed in. When it changes mid-session the app raises a toaster ("A new version is available"), waits **2.5s**, then signs out and reloads — so tokens, `localStorage`, and the persisted React Query cache (`localStorage["commerce"]`) all reset to the new build.
+
+Ported from toga25-supply (`force-logout-on-deployment`). Two commerce-only differences:
+- **Mounted as `<DeploymentGuard />` inside `AuthLayout`**, not in `AuthContext`. `ToasterProvider` sits **below** `AuthProvider` in `App.tsx`, so the context that owns sign-out cannot raise a toaster; the guard component is inside both providers.
+- **Baseline lives only in `localStorage["deployment-version"]`**, listed in `AUTH_STORAGE_KEYS` so logout clears it. No baseline → the check is skipped, which is what stops a sign-out loop.
+
+## How it works
+
+1. Query `META_LAST_REFRESH_DATETIME`, `enabled` only while authenticated, `staleTime: 0`, `refetchOnWindowFocus: true`, `refetchInterval` **5 minutes**. The old version refetched only on navigation, so an idle tab never noticed a deploy.
+2. First observation writes the baseline and never signs out.
+3. A later differing value → toaster → 2.5s timer → `logout()` + reload.
+4. `logout()` clears `AUTH_STORAGE_KEYS`, including the baseline, so the next login just re-baselines.
+
+## Gotchas
+
+- **⚠ Do not depend an effect on `addToaster`.** It is rebuilt on every `ToasterProvider` render, and raising the toaster re-renders that provider — the effect re-ran and its cleanup cleared the `setTimeout` it had just set, so the notice showed and the sign-out never fired. Keep unstable callbacks in refs and depend only on the stable value.
+- **⚠ The "already fired" flag must be module scope, not `useRef`.** The guard is mounted inside `AuthLayout`; a route change remounts it and a per-mount ref resets to `false`, so the notice reappeared on every navigation. Also do not clear the timer on unmount.
+
+## Change history
+- 2026-09-25 — Built for commerce: moved out of `AuthContext` into `<DeploymentGuard />` so a toaster can be shown; added 5-min poll + focus refetch; baseline key added to `AUTH_STORAGE_KEYS`. TRUE-81991. (apeterson)

package/knowledge/2.0/apps/toga2-commerce/features/page-loading-transitions.md

@@ -0,0 +1,39 @@
+---
+title: Skeleton → content transitions (AnimatePresence mode, layout jump, blank gap)
+framework: "2.0"
+repo: toga2-commerce
+project: TOGa Commerce
+client: shared
+type: feature
+status: active
+updated: 2026-09-25
+owners: [apeterson]
+files:
+  - toga2-commerce/src/pages/Account/AccountPage.tsx
+  - toga2-commerce/src/pages/Home/HomePage.tsx
+  - toga2-commerce/src/pages/Home/viewModel/useHomeViewModel.ts
+related:
+  - ../architecture.md
+  - ./storefront-persona-gating-and-home-counts.md
+---
+
+How commerce swaps a loading skeleton for real content with framer-motion; open for page jump/flicker or a blank gap while loading.
+
+## Summary
+
+Page-level loading states are framer-motion `AnimatePresence` swaps between a shimmer skeleton and the loaded content, using `fadeInOutVariants` (exit duration **0.3s**).
+
+## How it works
+
+`AnimatePresence` defaults to `mode="sync"`: the exiting child stays in layout while the entering child mounts, so both heights sum, then drop. Page-level swaps must use **`mode="wait"`**.
+
+Measured on a cold `/account` load with `sync`: page height 1300 → **1962** (content mounts while the 520px shimmer is still in flow) → 1442 when the shimmer is finally removed. The 305ms between the two jumps matches the 0.3s exit exactly. With `mode="wait"`: 1300 → 1442, one step.
+
+## Gotchas
+
+- **⚠ `mode="sync"` (the default) double-counts height** on any skeleton→content swap. Two visible jumps.
+- **⚠ Open — HomePage shows a blank white gap, not a jump.** `src/pages/Home/HomePage.tsx` (~line 488) renders `{!isLoading && (<AnimatePresence>{filteredItems}</AnimatePresence>)}`. `isLoading` comes from `homeDataState.status !== "ready"` in `useHomeViewModel` and flips false **before** `filteredItems` is populated, so the skeleton unmounts with nothing to replace it. Frame-by-frame: 4.10s skeleton cards → 4.30s blank card area → 4.40s real cards. Fix belongs in the view model's readiness logic — and must not treat "filteredItems is empty" as not-ready, or a legitimate no-results state renders a skeleton forever.
+- **⚠ The `mode="wait"` fix is not shipped.** It sits in `git stash@{0}` in toga2-commerce as of 2026-09-25, unreviewed.
+
+## Change history
+- 2026-09-25 — Documented `AnimatePresence` sync-vs-wait layout jump (measured) and the still-open HomePage blank gap. (apeterson)

package/knowledge/2.0/apps/toga2-commerce/features/sso-redirect-and-session-gating.md

@@ -87,5 +87,6 @@ api2 **rotates** the refresh token. Concurrent 401s each spent a token the other
 
 ## Change history
 - 2026-09-25 — Recorded that `GET /domains` is cached (`Core.Records` id 1, `ttlCache = 15`), the likely reason freshly inserted SSO rows still fall through to `/login` (rgirish)
+- 2026-09-25 — Deep links now survive sign-in: `PrivateRoute` saves before redirecting, one consumer per path, `onSuccess` navigates removed; header/footer logos point at `/home`. Known gap: the saml gateway always returns to `/`. TRUE-81991. (apeterson)
 - 2026-09-22 — Public token moved out of `localStorage`; `hasSession()` + identity epoch + `AUTH_STORAGE_KEYS` added; SSO sign-in screen replaces the auto IdP jump; open-redirect and SSO-URL-scheme holes closed; single-flight refresh. TRUE-81991 (`e546db3d`). (apeterson)
 - 2026-09-21 — Blank page at `/` fixed: gate on stored `user.uuid`, `AuthRedirect` renders the spinner instead of `null`. Branch `TRUE-82172` (`1eebdd96`, `3dc53d9a`), **not merged or deployed**. (tcox)

package/knowledge/2.0/apps/toga2-commerce/workflows/local-development-hosts.md

@@ -0,0 +1,37 @@
+---
+title: Running toga2-commerce locally (tenant hosts, not localhost)
+framework: "2.0"
+repo: toga2-commerce
+project: TOGa Commerce
+client: shared
+type: workflow
+status: active
+updated: 2026-09-25
+owners: [apeterson]
+files:
+  - toga2-commerce/vite.config.ts
+  - toga2-commerce/package.json
+related:
+  - ../architecture.md
+  - ./amplify-build-and-deploy.md
+  - ../features/sso-redirect-and-session-gating.md
+---
+
+Commerce cannot run on `localhost`; use a tenant hostname in `/etc/hosts`. Open when local dev bounces straight to `/login`.
+
+## Steps
+
+1. Add to `/etc/hosts`, pointing at `127.0.0.1`: `compass.togacommerce`, `compasscanada.togacommerce`, `quad.togacommerce` (these are the exact hosts allowed in `vite.config.ts`). For `npm run sandbox-client` also add `client.sandbox.togacommerce`.
+2. Start Vite and open the tenant host, never `http://localhost:<port>`.
+
+## Why localhost fails
+
+The tenant is resolved from `window.location.hostname`, and api2 checks the request `Origin` against `Core.Domains`. An unregistered origin returns **401** → the axios interceptor logs out → the app lands on `/login` with storage cleared. Copying tokens from another origin into `localStorage` does not help.
+
+## Gotchas
+
+- **⚠ `npm run sandbox-client` dies with `getaddrinfo ENOTFOUND`** until `client.sandbox.togacommerce` has its own hosts entry.
+- **⚠ A missing hosts entry looks like an auth bug.** The symptom is an instant redirect to `/login`, not a network error.
+
+## Change history
+- 2026-09-25 — Documented after tracing "cannot sign in locally" to the Origin/`Core.Domains` check. (apeterson)

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

@@ -0,0 +1,5 @@
+# toga25-blox (TOGa Blox 2.5) — 2.0 knowledge
+
+| Doc | Summary |
+|-----|---------|
+| [TOGa Blox 2.5 — Architecture](architecture.md) | Shared React+TS SOURCE library for the new platform apps (toga25-desk, toga25-iq, toga2-template, future apps); read the ADR for full detail, not this stub. |

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

@@ -0,0 +1,47 @@
+---
+title: TOGa Blox 2.5 — Architecture
+framework: "2.0"
+repo: toga25-blox
+project: TOGa Blox 2.5
+client: shared
+type: architecture
+status: active
+updated: 2026-09-26
+owners: [jcardinal]
+files:
+  - toga25-blox/src
+related: []
+---
+Shared React+TS SOURCE library for the new platform apps (toga25-desk, toga25-iq, toga2-template, future apps); read the ADR for full detail, not this stub.
+
+## Summary
+
+`toga25-blox` is a fresh, **source-shared** (git, not npm) React+TS library that replaces
+`toga-blox` for **new-platform apps only** (toga25-desk, toga25-iq, toga2-template, future
+apps). Apps import blox **source** from a sibling clone — `@toga/blox/<entry>` resolves via
+Vite alias to `../toga25-blox/src/<entry>/index.ts`. No build, no publish, no npm version.
+Deploy clones `toga25-blox` on the app's own branch at build time. Old npm `toga-blox` stays
+on `toga25-supply` / `toga2-commerce` / `toga2-view` / `toga2-hub` — do not port those apps to
+this repo. Full decision + rejected alternatives + consequences: `docs/decisions/0001-platform-frontend-architecture.md` in the toga25-blox repo — read that for anything beyond these rules.
+
+**Critical rules:**
+- **Reuse order:** an existing `toga25-blox` piece → a piece already built in another
+  new-platform app (promote it to blox) → only then build new. Never duplicate.
+- **Import boundary:** apps may import only `@toga/blox/<entry>` (the public entry barrel) —
+  lint blocks deeper paths. Blox never imports app code.
+- **Layer order (nothing imports upward):** `lib` < `core` < `tenancy` < `theme` < `surface`
+  < `ui` < `overlay` < `forms` < `data-table`.
+- **Blox changes are additive-only on a shared branch:** add the new API, migrate apps, then
+  remove the old one. A breaking edit can down every app building on that branch — see the
+  ADR's merge-gate + `BLOX_REF` pin guards before touching shared entries.
+- **At kickoff, read `INVENTORY.md`** in the local `toga25-blox` checkout (path from Claude
+  memory `repo-path-toga25-blox`, default `C:\WWW\toga25-blox`). It is generated from code and
+  is the **only** list of blox pieces (entry, name, one-line docblock, consuming apps) —
+  **never copy it into this KB**, it goes stale immediately.
+- **After changing blox, run `npm run inventory`** in `toga25-blox` (also enforced by the
+  blox PR check) to regenerate `INVENTORY.md`.
+
+## Related
+
+- ADR: `docs/decisions/0001-platform-frontend-architecture.md` (toga25-blox repo).
+- Old npm lib for legacy 2.0 apps: [toga-blox architecture](../toga-blox/architecture.md).

package/knowledge/2.0/apps/toga25-supply/features/side-navigation-and-default-route.md

@@ -6,8 +6,8 @@ project: TOGa 2.5 Supply
 client: shared
 type: feature
 status: active
-updated: 2026-09-16
-owners: [bala]
+updated: 2026-09-28
+owners: [bala, apeterson]
 files:
   - toga25-supply/src/routes.tsx
   - toga25-supply/src/layout/AppLayout/viewModel/useAppLayoutViewModel.ts
@@ -15,10 +15,12 @@ files:
   - _underscore/Model/Core/Surface.php
 related:
   - ./surface-frontend.md
+  - ./transfer-orders-page.md
   - ../../_underscore/features/surface-resolver.md
   - ../../_underscore/features/acl-permission-chain.md
   - ../../../1.0/apps/tools/features/persona-gated-navigation.md
   - ../../../../clients/compass-usa/workflows/granting-navigation-access.md
+  - ../../../../clients/quad/workflows/granting-internal-admin-navigation.md
 ---
 
 2.5 nav/routes/landing are 100% backend-driven by the `navigation` surface; a user with zero visible nav elements gets a BLANK page reported as "can't log in" — open when a login "fails" but auth actually succeeded.
@@ -32,6 +34,21 @@ Durable lesson: a user whose roles grant **zero** visible nav elements gets a **
 ## How it works
 
 1. `useAppLayoutViewModel` fetches `GET /v2/surfaces/meta?slug=navigation` and builds `sideNavItems` from the bundle's elements: `elements.filter((el) => el.isVisible && elementPath(el))`, sorted by `sortOrder`. `isVisible` comes from the server-side `SurfaceOverrides` cascade — see [Surface Resolver](../../_underscore/features/surface-resolver.md).
+
+   **Every nav element ships Core-base `isVisible = 0`**, so with no override the entry is hidden for
+   everyone. The canonical `Core.SurfaceElements` map for `Core.Surfaces.id = 39` (slug `navigation`) —
+   the ids you need to write an override row:
+
+   | Element id | `config.path` | Nav item | `sortOrder` |
+   |---|---|---|---|
+   | 109 | `sales-orders` | Sales Orders | 10 |
+   | 110 | `inventory` | Inventory | 20 |
+   | 111 | `items` | Items | 30 |
+   | 112 | `vendor-items` | Vendor Items | 40 |
+   | 113 | `bundles` | Bundles | 50 |
+   | 114 | `service-requests` | Service Requests | 60 |
+   | 190 | `transfer-orders` | Transfer Orders | — |
+
 2. It exposes `sideNavPaths` (same list, leading slash stripped) plus `isNavReady = !isLoading && surfaceMeta !== null`.
 3. `routes.tsx` → `AllowedRoutes` maps `sideNavPaths` through a **`ROUTE_REGISTRY`** keyed by path segment (`sales-orders`, `items`, `inventory`, `vendor-items`, `bundles`, `service-requests`), drops unknown keys, and takes the **first survivor** as the landing route:
 
@@ -79,3 +96,6 @@ That trailing silence is the tell: the app never picked a page, so it never aske
 - **`isNavReady` is not an ACL signal, it is a "bundle arrived" signal.** `routes.tsx` aliases it as `isAclReady`, which reads like a permission check but is only `!isLoading && surfaceMeta !== null`. An empty-but-successful bundle is "ready".
 - **Do not chase `AclActionPermissions` for a missing 2.5 menu item.** The `navigation-*` `Core.AclActions` rows are inert here — no `SurfaceElement` on `appId = 1` declares an `aclActionId`. The only lever is a role-scoped `SurfaceOverrides` `IS_VISIBLE = '1'` row. Full reasoning in [acl-permission-chain](../../_underscore/features/acl-permission-chain.md).
 - **Verifying a nav fix requires a LOGOUT, not a reload.** The surface bundle is cached with `staleTime`/`gcTime` `Infinity` and persisted to `localStorage` under `supply-chain-query-cache`. See [Surface Frontend](./surface-frontend.md).
+
+## Change history
+- 2026-09-28 — Added the canonical `Core.SurfaceElements` id → path map for surface 39 (incl. 190 `transfer-orders`); it was previously only in the Compass workflow doc (apeterson)

package/knowledge/CONVENTIONS.md

@@ -115,7 +115,7 @@ repo: worker2             # on-disk repo (matches folder + registry); omit for p
 project: Worker           # logical project name (from registry)
 client: shared            # "shared" for app docs; a real client slug for client docs
 type: feature             # feature | client-feature | workflow | architecture | standard
-status: active            # active | draft | deprecated
+status: active            # active | draft | deprecated | deferred
 updated: 2026-06-08
 owners: [jcardinal]
 files:                    # the doc's PRIMARY source files only (doc → code bridge) — a handful
@@ -165,6 +165,30 @@ standalone doc. Only a recurring/systemic failure class warrants its own record,
 _Elevated_ docs (architecture, standard) are senior-owned; `capture` flags any change
 to them with ⚠ so the developer knows what they're approving.
 
+## Where knowledge lives (one place per fact)
+
+Every fact has exactly one home — never duplicate it into a second place.
+
+- **Generated-from-code files live with the code**, not in the KB — e.g. `toga25-blox`'s
+  `INVENTORY.md`, a repo's docs index. They regenerate from source and go stale the moment
+  they're copied elsewhere. Kickoff/capture may be told to *read* one; never to *paste* it in.
+- **Everything a person must know lives in the team KB** — decisions, rules, gotchas,
+  architecture. Not a generated file, not a stale wiki page.
+- **App docs lifecycle (pre-MVP → launch → post-launch):**
+  1. **Before MVP**, an in-development app's knowledge lives in the app repo's own `docs/`.
+     The KB carries only a `registry.json` entry + a small `architecture.md` **stub**
+     pointing at the repo's docs (see `toga25-desk`/`toga25-iq` stubs) — never the real
+     content.
+  2. **At MVP launch**, all of that repo `docs/` knowledge **moves into the KB** (proper
+     `architecture.md` + `features/*.md`), and the stub is replaced.
+  3. **After launch**, the repo keeps only `README`, `CLAUDE.md`, and generated files
+     (inventories, indexes) — the durable knowledge lives in the KB, not the repo.
+- **Deferred features** (designed, not yet built) discovered after an app's launch go in
+  that app's KB folder as `type: feature`, `status: deferred` — not a separate backlog doc.
+- **The app template's starter docs** (in `toga2-template`) are the **template itself** —
+  boilerplate every new app copies and edits — not app knowledge about any one app. They stay
+  in that repo, not the KB.
+
 ## Required sections
 
 Every **feature**, **client-feature**, and **workflow** doc must include a

package/knowledge/INDEX.md

@@ -22,7 +22,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 - **_underscore** (_Underscore) _(framework core)_ — 90 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
 - **worker2** (Worker) — 80 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
 - **api2** (API) — 26 doc(s) → [2.0/apps/api2/INDEX.md](2.0/apps/api2/INDEX.md)
-- **dbchanges2** (Database Changes) _(framework core)_ — 20 doc(s) → [2.0/apps/dbchanges2/INDEX.md](2.0/apps/dbchanges2/INDEX.md)
+- **dbchanges2** (Database Changes) _(framework core)_ — 21 doc(s) → [2.0/apps/dbchanges2/INDEX.md](2.0/apps/dbchanges2/INDEX.md)
 - **toga2-supply** (TOGa Supply) — 9 doc(s) → [2.0/apps/toga2-supply/INDEX.md](2.0/apps/toga2-supply/INDEX.md)
 - **saml** (SAML SSO Gateway) — 9 doc(s) → [2.0/apps/saml/INDEX.md](2.0/apps/saml/INDEX.md)
 - **apiproxy** (API Proxy) — 1 doc(s) → [2.0/apps/apiproxy/INDEX.md](2.0/apps/apiproxy/INDEX.md)
@@ -32,10 +32,11 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 - **talos-backend** (TOGa Talos Backend) — 1 doc(s) → [2.0/apps/talos-backend/INDEX.md](2.0/apps/talos-backend/INDEX.md)
 - **voice-to-voice** (TOGa Voice) — 4 doc(s) → [2.0/apps/voice-to-voice/INDEX.md](2.0/apps/voice-to-voice/INDEX.md)
 - **ai-bdr** (AI-BDR) — 13 doc(s) → [2.0/apps/ai-bdr/INDEX.md](2.0/apps/ai-bdr/INDEX.md)
-- **toga2-commerce** (TOGa Commerce) — 26 doc(s) → [2.0/apps/toga2-commerce/INDEX.md](2.0/apps/toga2-commerce/INDEX.md)
+- **toga2-commerce** (TOGa Commerce) — 29 doc(s) → [2.0/apps/toga2-commerce/INDEX.md](2.0/apps/toga2-commerce/INDEX.md)
 - **toga25-supply** (TOGa 2.5 Supply) — 22 doc(s) → [2.0/apps/toga25-supply/INDEX.md](2.0/apps/toga25-supply/INDEX.md)
 - **toga25-iq** (TOGa IQ) — 1 doc(s) → [2.0/apps/toga25-iq/INDEX.md](2.0/apps/toga25-iq/INDEX.md)
 - **toga25-desk** (TOGa Desk 2.5) — 1 doc(s) → [2.0/apps/toga25-desk/INDEX.md](2.0/apps/toga25-desk/INDEX.md)
+- **toga25-blox** (TOGa Blox 2.5) — 1 doc(s) → [2.0/apps/toga25-blox/INDEX.md](2.0/apps/toga25-blox/INDEX.md)
 - **toga-blox** (TOGa Blox) — 15 doc(s) → [2.0/apps/toga-blox/INDEX.md](2.0/apps/toga-blox/INDEX.md)
 - **bdr** (BDR) — 0 doc(s) → [2.0/apps/bdr/INDEX.md](2.0/apps/bdr/INDEX.md)
 

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

@@ -27,6 +27,7 @@
 | [Persona Model & Levy-Sector Gating (worker2 PEOPLE cron)](features/persona-model-and-levy-gating.md) | 2.0 | Compass USA catalogue visibility is driven by **personas** in `Client_Compass`. |
 | [Compass Sales-Order Line-Number Renumbering (and why it hangs off the SO hooks)](features/sales-order-line-renumbering.md) | 2.0 | How Compass keeps SO lines numbered 1..N with no gaps, why the renumber rides the parent SO hooks, and the two-phase SQL that avoids a duplicate-key fatal; open |
 | [Compass SAML SSO (Entra) — identity mapping, the @togatech.com bypass, and per-environment enablement](features/saml-sso.md) | 2.0 | How Compass users are matched from an Entra SAML assertion, the hardcoded `@togatech.com` test bypass that is live in production, and what it takes to turn SSO |
+| [Compass SSO signs every @togatech.com user in as one hardcoded user (GINA PRINCE, 4273)](features/sso-devteam-user-shortcut.md) | 2.0 | Why an internal dev signing into a Compass app via SSO lands as someone else; open for "I'm signed in as the wrong user" on Compass. |
 | [Stranded Approval Reassignment (repointing approvals off dead duplicate Compass Users rows)](features/stranded-approval-reassignment.md) | 2.0 | The engine that repoints approvals stranded on dead duplicate Compass Users rows onto the live account; open when approvals are stuck on a re-hired employee's o |
 | [Compass: where a `TrackingNumbers` row comes from (invoice sync, NOT the ASN) and how it reaches a customer](features/tracking-number-origin-and-asn-link.md) | 1.0 | Why a Compass TrackingNumbers row is born from the invoice sync (not the ASN) and why `dtCreated` is the wrong clock for any shipping notification/SLA; open bef |
 | [Compass USA](profile.md) | 2.0 | Compass USA client profile: platforms, vendors/integrations, and the key features/traps across its 1.0+2.0 supply-chain commerce stack; open first when starting |

package/knowledge/clients/compass-usa/features/sso-devteam-user-shortcut.md

@@ -0,0 +1,32 @@
+---
+title: Compass SSO signs every @togatech.com user in as one hardcoded user (GINA PRINCE, 4273)
+framework: "2.0"
+project: _Underscore
+client: compass-usa
+type: client-feature
+status: active
+updated: 2026-09-25
+owners: [apeterson]
+files:
+  - _underscore/Model/Compass/ClientAuthentication.php
+related:
+  - ../profile.md
+  - ../../../2.0/apps/toga2-commerce/features/sso-redirect-and-session-gating.md
+---
+
+Why an internal dev signing into a Compass app via SSO lands as someone else; open for "I'm signed in as the wrong user" on Compass.
+
+## Summary
+
+`_Model_Compass_ClientAuthentication::getAuthenticatedSsoUser()` checks the SAML NameID. If it contains `@togatech.com` it returns `new _Model_Compass_User(4273)` (**GINA PRINCE**, `_isSuperAdmin = 1`) instead of matching on `c_hrEmpUsername`. The source comment says "return gina's user if testing on devteam".
+
+So **every** TOGA employee signing into **any** Compass app through SSO is that one shared super-admin user. Deliberate test shortcut, not a bug — but it costs real time to trace, because the behaviour starts in the front end and only shows up down in the framework model.
+
+## Gotchas
+
+- **⚠ Shared identity.** Two devs signed in at once are the same user — carts, orders and audit rows attribute to 4273.
+- **⚠ Elevated by accident.** That user is a super admin, so devteam testing never sees normal-permission behaviour.
+- **⚠ Not reachable by credentials.** Bypassing it needs a non-SSO sign-in path; see the proposed `/login?local=1` flag in the commerce SSO doc.
+
+## Change history
+- 2026-09-25 — Recorded after tracing a wrong-user SSO sign-in from commerce through the saml gateway into `_underscore`. (apeterson)

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

@@ -39,6 +39,7 @@ related:
   - features/oneuptime-ma-refresh-order-monitor.md
   - workflows/catalog-fold-reversal.md
   - features/asn-to-item-fulfillment.md
+  - features/sso-devteam-user-shortcut.md
   - features/odp-strategic-systems-asn-csv-import.md
   - features/multi-tier-tracking-and-serial-mirroring.md
   - features/order-fulfillment-status-per-line.md

package/knowledge/clients/compass-usa/workflows/granting-navigation-access.md

@@ -6,7 +6,7 @@ project: Database Changes
 client: compass-usa
 type: workflow
 status: active
-updated: 2026-09-16
+updated: 2026-09-28
 owners: [apeterson, bala]
 files:
   - dbchanges2/Client_Compass/2026-08-12a - NavigationRoleGrants.sql
@@ -16,6 +16,7 @@ files:
 related:
   - ./granting-persona-bundle-access.md
   - ../profile.md
+  - ../../quad/workflows/granting-internal-admin-navigation.md
   - ../../../2.0/apps/_underscore/features/surface-resolver.md
   - ../../../2.0/apps/dbchanges2/features/surface-layer-schema.md
   - ../../../2.0/apps/toga25-supply/features/surface-frontend.md
@@ -34,15 +35,7 @@ How to give a Compass user another user's toga25-supply menu items via role-scop
 
 So visibility = exactly one thing: a `Client_Compass.SurfaceOverrides` row with `attribute = 'IS_VISIBLE'`, `value = 1`, scoped to a `roleId` the user holds.
 
-`Core.SurfaceElements` ids for surface slug `navigation`:
-| Element id | `config.path` | Nav item | `sortOrder` |
-|---|---|---|---|
-| 109 | `sales-orders` | Sales Orders | 10 |
-| 110 | `inventory` | Inventory | 20 |
-| 111 | `items` | Items | 30 |
-| 112 | `vendor-items` | Vendor Items | 40 |
-| 113 | `bundles` | Bundles | 50 |
-| 114 | `service-requests` | Service Requests | 60 |
+Element ids for surface 39 (`navigation`) live in [side navigation & default route](../../../2.0/apps/toga25-supply/features/side-navigation-and-default-route.md) — do not duplicate them here.
 
 The Compass override map (all `IS_VISIBLE`, `value = 1`, `personaId` NULL, `languageId` NULL):
 | Element | Roles granting visibility |
@@ -122,6 +115,7 @@ Role 16's Vendor Items gap is **left open on purpose** — widening nav for ever
 - **Role permissions resolve as a union**, so an additive `Users_Roles` row never takes access away — see [ACL Permission Chain](../../../2.0/apps/_underscore/features/acl-permission-chain.md). The flip side is that it also grants everything else the role carries.
 - **⚠ These ids sit OUTSIDE the team-reserved blocks.** The reserved-id table in [Surface Resolver](../../../2.0/apps/_underscore/features/surface-resolver.md) and [surface-layer-schema](../../../2.0/apps/dbchanges2/features/surface-layer-schema.md) lists `Core.Surfaces` **41–43** / `Core.SurfaceElements` **125–146**. The `navigation` surface predates those blocks and lives at elements **109–114**. Read the reserved blocks as "the decision-surface reseed", not as an inventory of all surface ids.
 - **Verifying the change requires a LOGOUT, not a reload.** Surface meta is cached `staleTime`/`gcTime` `Infinity` **and persisted to `localStorage`** under `supply-chain-query-cache`, so a hard reload restores the stale bundle and proves nothing. There is no server-side surface cache. Detail in [Surface Frontend](../../../2.0/apps/toga25-supply/features/surface-frontend.md).
+- **The `Agilant - Administrators` role may carry ZERO `AclFieldPermissions`.** `Client_Compass` role 9 has none — it is a nav/record-scoping role only; field reads come from the other roles the same user holds. `Client_Compasscanada` role **10** is the same role under a different id. Same pattern applied to Quad 2026-09-28: [Quad internal-admin navigation](../../quad/workflows/granting-internal-admin-navigation.md).
 - **`aclActionId` is NULL on all six nav elements** — resist the instinct to reach for `AclActionPermissions` when a menu item is missing. It is always a `SurfaceOverrides` row.
 
 ## Related
@@ -133,3 +127,6 @@ Role 16's Vendor Items gap is **left open on purpose** — widening nav for ever
 - [Re-runnable additive INSERTs](../../../2.0/apps/dbchanges2/features/rerunnable-additive-inserts.md)
 - [ACL Permission Chain](../../../2.0/apps/_underscore/features/acl-permission-chain.md)
 - [Side navigation & default route](../../../2.0/apps/toga25-supply/features/side-navigation-and-default-route.md)
+
+## Change history
+- 2026-09-28 — Element-id map moved to the shared side-nav doc; recorded that role 9 holds no `AclFieldPermissions` and that Compass Canada's equivalent is role 10 (apeterson)

package/knowledge/clients/quad/INDEX.md

@@ -7,3 +7,4 @@
 | [Quad: PO + ASN email importer (import_po_and_asn.php)](features/po-asn-email-import.md) | 1.0 | Quad's inbox-driven PO/ASN CSV importer and its 2026-08 failure classes; open when a Quad PO/ASN email jams the mailbox, fails EV-12, or you touch `import_po_an |
 | [Quad Graphics](profile.md) | 2.0 | Quad Graphics is a TOGA 2.0 client on the `_underscore` platform, prod schema `Client_Quad`. |
 | [Quad Graphics — reversing the 30-item catalog fold (storefront-assortment recovery)](workflows/catalog-fold-reversal.md) | 2.0 | How the 2026-08-31 catalog-blind item merge damaged Quad's storefront and how the reversal was built; open when assessing/repairing catalog-fold damage on a two |
+| [Giving Quad's internal TOGA staff extra toga25-supply nav (the `Agilant - Administrators` role pattern)](workflows/granting-internal-admin-navigation.md) | 2.0 | How to surface extra 2.5 Supply pages to internal TOGA staff on a tenant without showing them to the client's own users — Quad's first internal-admin role; open |

package/knowledge/clients/quad/profile.md

@@ -16,12 +16,13 @@ project: _Underscore
 client: quad
 type: profile
 status: active
-updated: 2026-09-17
+updated: 2026-09-28
 owners: ["jcardinal", "bala", "apeterson", "ajean"]
 files: []
 related:
   - ../../2.0/apps/toga2-commerce/features/storefront-persona-gating-and-home-counts.md
   - ./workflows/catalog-fold-reversal.md
+  - ./workflows/granting-internal-admin-navigation.md
   - ./features/po-asn-email-import.md
   - ./features/enter-po-details-vendor-selection-ev12.md
   - ../../2.0/apps/_underscore/features/sales-order-po-number-sourcing.md
@@ -162,4 +163,9 @@ Client-specific DB change-sets live in `dbchanges2/Client_Quad/`.
   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).
+- **Internal-staff nav is its own role (2026-09-28).** Quad now follows the Compass
+  `Agilant - Administrators` pattern: a dedicated role carries the 2.5 Supply `SurfaceOverrides`
+  nav grants for Items/Vendor Items so Quad's own `@quad.com` users (five of the seven holders of
+  role 7 `Global Admin`) do not get them. Migration written, **not yet run**. See
+  [Quad internal-admin navigation](./workflows/granting-internal-admin-navigation.md).
 - This profile is a starting point; expand as more Quad-specific behavior is captured.

package/knowledge/clients/quad/workflows/granting-internal-admin-navigation.md

@@ -0,0 +1,81 @@
+---
+title: Giving Quad's internal TOGA staff extra toga25-supply nav (the `Agilant - Administrators` role pattern)
+framework: "2.0"
+repo: dbchanges2
+project: Database Changes
+client: quad
+type: workflow
+status: active
+updated: 2026-09-28
+owners: ["apeterson"]
+files:
+  - dbchanges2/Client_Quad/2026-09-28a - AgilantAdministratorsRoleAndItemsNav.sql
+related:
+  - ../profile.md
+  - ../../compass-usa/workflows/granting-navigation-access.md
+  - ../../../2.0/apps/toga25-supply/features/side-navigation-and-default-route.md
+  - ../../../2.0/apps/_underscore/features/acl-permission-chain.md
+  - ../../../2.0/apps/dbchanges2/features/rerunnable-additive-inserts.md
+---
+
+How to surface extra 2.5 Supply pages to internal TOGA staff on a tenant without showing them to the client's own users — Quad's first internal-admin role; open for "internal user can't see page X" on any tenant.
+
+## Summary
+
+Internal TOGA staff need pages (Items, Vendor Items, Bundles) that the tenant's own staff must
+**not** see. The house pattern is a **dedicated `Agilant - Administrators` role** that carries the
+nav overrides and nothing else — `Client_Compass` role **9**, `Client_Compasscanada` role **10**,
+and as of 2026-09-28 a new role on `Client_Quad`. Nav gating itself is the shared
+[`SurfaceOverrides IS_VISIBLE` mechanism](../../../2.0/apps/toga25-supply/features/side-navigation-and-default-route.md)
+(element-id map lives there); this doc is only about **which role** gets the override.
+
+Never hang an internal nav grant on a shared admin role. `Client_Quad` role **7** (`Global Admin`)
+is held by **7** users, **five of them `@quad.com`** (MNICHOLS, JOSHUAMARTI, DJPUTNEY, mnaber,
+JACEDWARDS) — adding elements 111/112 there would have shown Items and Vendor Items to Quad's own
+staff. That is a tenant-wide behavior change dressed up as a per-user fix.
+
+## Steps
+
+1. **Check whether the data ACL is already in place** — usually it is, making this nav-only.
+   `Client_Quad.AclRecordPermissions` already grants record **19** (`vendor-items`) to role **1**
+   (Base), full CRUD, `appId` NULL, and record **21** (`items`) to role **1** at `appId = 1`. So
+   every Quad user could already *read* the data; only the menu entry was missing.
+2. **Count the users on the candidate role before granting on it** (`Users_Roles` joined to
+   `Users`). Any `@<client-domain>` holder disqualifies the role for an internal-only grant.
+3. **Create a dedicated `Agilant - Administrators` role** in the client DB if the tenant has none,
+   and assign only the internal users the developer names. Quad got **`devteam@togatech.com` only**;
+   the other three `@togatech.com` Quad users (JWise, NSchenkel, rgreen) were deliberately left off.
+4. **Add role-scoped `SurfaceOverrides` rows** (`surfaceId` 39, the element ids, `IS_VISIBLE` = `'1'`,
+   `personaId`/`languageId` NULL) for that new role. Nothing else — no `AclRecordPermissions`, no
+   `AclFieldPermissions`, so the migration cannot widen data access.
+5. **Hand the file to the developer to run.** Verify in the app by **logging out and back in** —
+   the surface bundle is cached in `localStorage`, so a reload proves nothing.
+
+### The 2026-09-28 Quad migration
+`dbchanges2/Client_Quad/2026-09-28a - AgilantAdministratorsRoleAndItemsNav.sql` — committed
+`a890c26` on branch `TRUE-82246`, **not yet run in any environment.** Three guarded statements,
+all inside `Client_Quad`: create the role, assign `devteam@togatech.com`, insert two
+`SurfaceOverrides` rows for elements **111** (`items`) and **112** (`vendor-items`). Core ids
+(39, 111, 112) are **hardcoded literals** — `Core` and `Client_<tenant>` are separate prod
+clusters, so the statement cannot join `Core.SurfaceElements` to resolve them.
+
+Quad's starting state for contrast: **one** nav override total (element 109 `sales-orders`, `roleId`
+**NULL** — i.e. tenant-wide) and no internal-admin role at all.
+
+## Gotchas
+
+- **⚠ `Core.Apps` id 1 = TOGa Supply, id 5 = TOGa Commerce.** Quad's role-7 grant on record 21
+  (`items`) is `appId = 5` — **Commerce, not Supply**. It reads like "Global Admin can already see
+  Items in Supply" and it cannot. Always read the `appId` on an `AclRecordPermissions` row before
+  concluding a role has Supply access.
+- **The internal-admin role may carry zero `AclFieldPermissions`.** `Client_Compass` role 9 has
+  **none** — it is a nav/record-scoping role only, and field reads come from the other roles the
+  same user holds. An empty field-permission set on this role is correct, not a broken grant.
+- **⚠ These facts were read from a LOCAL (beta/sandbox-derived) copy.** The prod client reader
+  `reader1.client.database.togahub.com` was unreachable on 2026-09-28 (`ERROR 2002 … (36)`).
+  Re-verify role ids, user lists and existing overrides against production before running the
+  migration there.
+
+## Change history
+- 2026-09-28 — Created; Quad's first `Agilant - Administrators` role + Items/Vendor Items nav
+  overrides written (not yet run), scoped away from `Global Admin` role 7 (apeterson)

package/knowledge/registry.json

@@ -223,13 +223,24 @@
     "project": "TOGa IQ",
     "framework": "2.0",
     "role": "app",
-    "dependsOn": []
+    "dependsOn": [
+      "toga25-blox"
+    ]
   },
   {
     "repo": "toga25-desk",
     "project": "TOGa Desk 2.5",
     "framework": "2.0",
     "role": "app",
+    "dependsOn": [
+      "toga25-blox"
+    ]
+  },
+  {
+    "repo": "toga25-blox",
+    "project": "TOGa Blox 2.5",
+    "framework": "2.0",
+    "role": "app",
     "dependsOn": []
   },
   {

package/knowledge.js

@@ -38,6 +38,9 @@ const REGISTRY = path.join(ROOT, 'registry.json');
 const FRAMEWORKS = ['1.0', '2.0', 'standalone'];
 const DOC_TYPES = ['feature', 'client-feature', 'workflow', 'architecture', 'standard', 'profile'];
 const ELEVATED_TYPES = ['architecture', 'standard'];
+// deferred = designed but not yet built (post-launch backlog living on the feature doc
+// itself, not a separate backlog file) — loads and searches exactly like `active`.
+const DOC_STATUSES = ['active', 'draft', 'deprecated', 'deferred'];
 
 /* Prime-cost guardrails — WARN-ONLY (never fail a commit/capture). These are
  * creep detectors, not hard limits, so a genuinely long-but-needed doc is allowed.
@@ -311,7 +314,7 @@ function cmdPreflight(args) {
         if (isChosen) {
             features = docs
                 .filter(d => d.file.startsWith(repoDir + path.sep) && d.data.type !== 'architecture' && matchQ(d))
-                .map(d => ({ path: d.rel, title: d.data.title || '', files: (d.data.files || []).join(', ') }));
+                .map(d => ({ path: d.rel, title: d.data.title || '', files: (d.data.files || []).join(', '), status: d.data.status || '' }));
         }
         const summary = (!isChosen && archDoc) ? (extractSection(archDoc.body, 'Summary') || firstSentence(archDoc.body)) : '';
         return {
@@ -356,7 +359,7 @@ function cmdPreflight(args) {
             .filter(d => path.basename(d.file) !== 'profile.md')
             .filter(d => !frameworks.length || !d.data.framework || frameworks.includes(d.data.framework))
             .filter(matchQ)
-            .map(d => ({ path: d.rel, title: d.data.title || '', framework: d.data.framework || '', type: d.data.type || '' }));
+            .map(d => ({ path: d.rel, title: d.data.title || '', framework: d.data.framework || '', type: d.data.type || '', status: d.data.status || '' }));
         client = {
             slug,
             title: (profileDoc && profileDoc.data.title) || slug,
@@ -385,7 +388,7 @@ function cmdPreflight(args) {
     const pushRepoRead = (r) => {
         if (r.chosen) {
             reads.push({ label: 'repo-architecture', repo: r.repo, path: r.architecture.path, exists: r.architecture.exists, content: r.architecture.exists ? contentFor(r.architecture.path) : undefined });
-            for (const f of r.features) reads.push({ label: 'feature', repo: r.repo, path: f.path, exists: true, title: f.title, content: contentFor(f.path) });
+            for (const f of r.features) reads.push({ label: 'feature', repo: r.repo, path: f.path, exists: true, title: f.title, status: f.status, content: contentFor(f.path) });
         } else {
             reads.push({ label: 'architecture-summary', repo: r.repo, role: r.role, path: r.architecture.path, exists: r.architecture.exists, lazy: true, summary: r.summary });
         }
@@ -570,7 +573,7 @@ function cmdSearch(args) {
         return true;
     });
     for (const m of matches) {
-        console.log(m.rel + '\t' + (m.data.title || '') + '\t' + (m.data.type || ''));
+        console.log(m.rel + '\t' + (m.data.title || '') + '\t' + (m.data.type || '') + (m.data.status === 'deferred' ? '\t[deferred]' : ''));
     }
 }
 
@@ -739,6 +742,7 @@ function cmdValidate() {
             if (!d.data[f]) { fail(`${d.rel}: missing frontmatter "${f}"`); ok = false; }
         }
         if (d.data.type && !DOC_TYPES.includes(d.data.type)) { fail(`${d.rel}: invalid type "${d.data.type}"`); ok = false; }
+        if (d.data.status && !DOC_STATUSES.includes(d.data.status)) { fail(`${d.rel}: invalid status "${d.data.status}"`); ok = false; }
         const isClientDoc = d.rel.startsWith('clients/');
         if (isClientDoc) {
             if (!d.data.client || d.data.client === 'shared') { fail(`${d.rel}: client doc must set a real "client"`); ok = false; }

package/package.json

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

package/skills/capture/SKILL.md

@@ -116,6 +116,11 @@ Assemble these fields, matching the `session-capture` agent's input contract **e
 
 That is the entire main-thread analysis job: summarize, do not investigate the KB.
 
+**If this session changed `toga25-blox` source**, remind the developer to run
+`npm run inventory` there (regenerates `INVENTORY.md`; also enforced by the blox PR check).
+Never write `toga25-blox`'s inventory contents into the KB — it is generated-from-code and
+lives only in the repo (see CONVENTIONS → "Where knowledge lives").
+
 ## Step 3 — Delegate to the `session-capture` subagent
 
 Spawn the subagent via the **Agent tool** with `subagent_type: session-capture`, passing the

package/skills/kickoff/SKILL.md

@@ -308,6 +308,10 @@ Do this now:
 2. As you read, hold the **load-bearing facts** you'll code against: the critical rules
    (naming prefixes, DB-access layer, dispatch pattern, response envelope, migration filename
    rules), the task-relevant feature entry points and **gotchas**, and any client variations.
+2b. **If `toga25-blox` is in `loadSet`**, after absorbing its KB docs and before the Step 5
+   summary, also read `INVENTORY.md` in its local checkout (`repo-path-toga25-blox` memory,
+   default `C:\WWW\toga25-blox`) — it is the only generated, always-current list of blox
+   pieces (entry, name, docblock, consuming apps). Never copy its contents into the KB.
 3. When you have read **every** resolved doc, run the completion sentinel to release the gate:
    ```bash
    node "<TEAM_REPO>/knowledge.js" kickoff-primed