toga-ai 1.0.31 → 1.0.33

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

@@ -3,4 +3,5 @@
 | Doc | Summary | Files |
 |-----|---------|-------|
 | [_underscore Framework Architecture](architecture.md) | `_underscore` is the shared PHP backend framework for **all 2.0 applications**. | _underscore/_underscore.php, _underscore/Loader.php, _underscore/Framework.php, _underscore/Model.php, _underscore/Database.php, _underscore/Query.php, _underscore/Route.php, _underscore/Component.php |
+| [Carrier Shipping Labels (UPS/FedEx) & NetSuite Item Fulfillment](features/carrier-shipping-labels.md) | Backend mechanics behind TOGa Supply's Fulfill & Ship: buying a carrier label (UPS/FedEx), persisting it, and creating the NetSuite Item Fulfillment with tracki | _underscore/Model/Client/ItemFulfillment.php, _underscore/Component/Library/Carriers/Ups/Ups.php, _underscore/Trait/Netsuite/ItemFulfillment.php, _underscore/Trait/Netsuite/SalesOrder.php, _underscore/Component/Library/NetSuite/NetSuite.php, _underscore/Model/Client/TrackingNumber.php, _underscore/Model/Client/ShippingMethod.php, _underscore/Model.php, _underscore/Cloud.php |
 | [Recursive Item Fulfillments (upstream mirroring)](features/recursive-item-fulfillments.md) | In a multi-tier supply chain a sales order (SO) spawns a purchase order (PO) that becomes another SO downstream, and so on. | _underscore/Model/Client/ItemFulfillment.php, _underscore/Model/Client/ItemFulfillmentItem.php, _underscore/Model/Client/ItemFulfillmentItemUnit.php, _underscore/Model/Client/ItemFulfillmentPackage.php, _underscore/Model/Compass/AdvanceShippingNotice.php, dbchanges2/Core/2026-02-13 - 75601 - RecursiveItemFulfillmentCreation.sql, dbchanges2/Core/2026-06-04 - RecursiveItemFulfillmentPut.sql |

package/knowledge/2.0/apps/_underscore/features/carrier-shipping-labels.md

@@ -0,0 +1,113 @@
+---
+title: Carrier Shipping Labels (UPS/FedEx) & NetSuite Item Fulfillment
+framework: "2.0"
+repo: _underscore
+project: _Underscore
+client: shared
+type: feature
+status: active
+updated: 2026-06-10
+owners: [mhammontree]
+files:
+  - _underscore/Model/Client/ItemFulfillment.php
+  - _underscore/Component/Library/Carriers/Ups/Ups.php
+  - _underscore/Trait/Netsuite/ItemFulfillment.php
+  - _underscore/Trait/Netsuite/SalesOrder.php
+  - _underscore/Component/Library/NetSuite/NetSuite.php
+  - _underscore/Model/Client/TrackingNumber.php
+  - _underscore/Model/Client/ShippingMethod.php
+  - _underscore/Model.php
+  - _underscore/Cloud.php
+related:
+  - ../architecture.md
+  - recursive-item-fulfillments.md
+  - ../../toga2-supply/features/fulfill-and-ship.md
+---
+
+## Summary
+
+Backend mechanics behind TOGa Supply's Fulfill & Ship: buying a carrier label
+(UPS/FedEx), persisting it, and creating the NetSuite Item Fulfillment with tracking
+number and label attached. Includes the **authoritative label-storage architecture
+decision** (dev lead Jeff, June 2026) that supersedes what the code currently does.
+
+## Key files / entry points
+
+- `upsShipmentApi` / `fedexShipmentApi` (scripted APIs on
+  `Model/Client/ItemFulfillment.php`): build the carrier request, call the carrier,
+  (currently) convert ZPL→PDF via Labelary, save the PDF to NetSuite File Cabinet +
+  the DB storage field, return `{ trackingNumber, pdfLabel, fileInternalId }` or
+  `{ error, trackingNumber }`. UPS path now checks `$shipmentResponse->success` and
+  fast-fails on an empty service code (it previously swallowed UPS errors and surfaced
+  a misleading "Failed to save PDF to NetSuite").
+- `_Component_Library_Carriers_Ups::submitShipmentRequest`
+  (`Component/Library/Carriers/Ups/Ups.php`): returns `{ success, errorMessage,
+  trackingNumber, encodedLabel }`.
+- `createNetsuiteItemFulfillment` (`Trait/Netsuite/ItemFulfillment.php`): builds the NS
+  IF from the SO, assigns serialized inventory, sets packages/tracking numbers.
+  **Returns the numeric NS internalId on success, an error string on failure**
+  (ambiguous return — callers must check `/^\d+$/`). Takes
+  `$labelFileInternalId = null` and attaches the label to the IF after creation
+  (`attachFileToRecord` was widened `private` → `protected` so the trait can call it
+  from client subclasses).
+- The trait is composed into **client-specific** subclasses
+  (`_Model_Growrk_ItemFulfillment extends _Model_Client_ItemFulfillment`), not the base
+  model.
+
+## Label-storage architecture (AUTHORITATIVE — dev lead Jeff, 2026-06)
+
+Supersedes the Labelary-PDF + manual-S3 approach:
+
+1. **Do NOT touch S3 by hand.** The model's `FIELD_STORAGE` abstraction, accessed via
+   the 2.0 API, already handles label fetch + storage.
+2. **Store the raw carrier response as a GIF**, not a Labelary-converted PDF.
+3. **Generate the printable PDF on demand**, combining the shipping label AND the
+   return label into one PDF (the browser print dialog handles one file at a time).
+   Leaning **backend** generation — `pdf-lib` (client-side) cannot embed GIF.
+
+Not yet implemented. Open questions before building: backend vs frontend for the
+GIF→PDF step; which existing 2.0 label-fetch/storage calls to build on. Combining
+shipping + return also depends on the return-label flow existing — outbound-only can
+come first.
+
+## `FIELD_STORAGE` mechanics (reference)
+
+`Model.php` handles storage fields separately from regular columns (write loop ~line
+393; read ~line 730). Config keys in `[_underscore]`: `model_storage_folder` → local
+folder mode (if set, S3 is never used); `model_storage_s3_bucket` +
+`model_storage_s3_folder` → S3 mode. Storage key/path (both modes):
+
+```
+<folder-or-s3-prefix>/<env (_Environment::$name)>/<database>/<TABLE>/<field>/<primaryKeyId>
+```
+
+e.g. `<prefix>/beta/Client_Growrk/TrackingNumbers/labelPdfFile/<id>` — named by numeric
+PK, **no extension**. Reads return the raw bytes verbatim (no base64/data-uri); writes
+store whatever value was assigned. `_Cloud::copyFileToS3` **re-throws** on AWS errors —
+if no exception reached the caller and execution continued, the write was never
+attempted.
+
+## Gotchas / known issues
+
+- UPS **test** endpoint (`wwwcie.ups.com`, debug mode) returns a constant tracking
+  number `1ZXXXXXXXXXXXXXXXX` + SAMPLE labels → `TrackingNumbers.number` UNIQUE
+  collision and File Cabinet duplicate-filename failures on repeat tests (see the
+  fulfill-and-ship doc for the cleanup SQL). Never in prod.
+- `upsShipmentApi` reads ship-to from the **Sales Order** (`shipToAddressId`), not the
+  Item Fulfillment — form-edited addresses never reach UPS.
+- UPS `AddressLine` max 35 chars/line; send an array of trimmed lines (FedEx already
+  does), not `line1 . ' ' . line2`.
+- `ShippingMethods.code` is carrier-scoped: UPS numeric (`03` Ground, `01` Next Day
+  Air), FedEx strings (`FEDEX_GROUND`). Empty code → UPS error 120500.
+- Serialized-inventory assignment fails ("Invalid issueinventorynumber reference key")
+  when the lookup isn't location-scoped and the SO has no Warehouse Location —
+  recommended: always scope `getInventoryNumberFromSerialNumber` by location.
+- `createNetsuiteItemFulfillment` doesn't set carrier/method on the NS IF — it defaults
+  (can show FedEx for a UPS shipment). Open item.
+
+## Related docs
+
+- [Fulfill & Ship (toga2-supply)](../../toga2-supply/features/fulfill-and-ship.md) —
+  frontend flow and success gating.
+- [Recursive Item Fulfillments](recursive-item-fulfillments.md) — interceptor-driven
+  upstream mirroring on the same models.

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

@@ -0,0 +1,6 @@
+# toga2-supply (TOGa Supply) — 2.0 knowledge
+
+| Doc | Summary | Files |
+|-----|---------|-------|
+| [TOGa Supply (toga2-supply) Architecture](architecture.md) | `toga2-supply` is the **React + Vite frontend** for TOGa Supply — warehouse fulfillment tooling (shipment selection, fulfill & ship against carrier APIs, NetSui | toga2-supply/src/api/toga.ts, toga2-supply/src/pages/ShipmentItems/view/ShipmentItemsPage.tsx, toga2-supply/src/pages/EditShipment/view/EditShipmentPage.tsx, toga2-supply/src/pages/EditShipment/api/UpdateShipmentApi.ts, toga2-supply/src/pages/Shipments/view/components/ShipmentsCardTableForm/ShipmentsCardTableForm.tsx |
+| [Fulfill & Ship](features/fulfill-and-ship.md) | Fulfill & Ship lets a warehouse user select sales-order line items, enter serials, pick a carrier/method, and in one action: create the Item Fulfillment records | toga2-supply/src/pages/ShipmentItems/view/ShipmentItemsPage.tsx, toga2-supply/src/pages/EditShipment/view/EditShipmentPage.tsx, toga2-supply/src/pages/EditShipment/view/components/forms/EditShipmentForm.tsx, toga2-supply/src/pages/EditShipment/api/UpdateShipmentApi.ts, toga2-supply/src/pages/Shipments/view/components/ShipmentsCardTableForm/ShipmentsCardTableForm.tsx, toga2-supply/src/pages/Shipments/api/ShipmentsApi.ts, _underscore/Model/Client/ItemFulfillment.php, _underscore/Trait/Netsuite/ItemFulfillment.php, _underscore/Component/Library/Carriers/Ups/Ups.php |

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

@@ -0,0 +1,73 @@
+---
+title: TOGa Supply (toga2-supply) Architecture
+framework: "2.0"
+repo: toga2-supply
+project: TOGa Supply
+client: shared
+type: architecture
+status: active
+updated: 2026-06-10
+owners: [mhammontree]
+files:
+  - toga2-supply/src/api/toga.ts
+  - toga2-supply/src/pages/ShipmentItems/view/ShipmentItemsPage.tsx
+  - toga2-supply/src/pages/EditShipment/view/EditShipmentPage.tsx
+  - toga2-supply/src/pages/EditShipment/api/UpdateShipmentApi.ts
+  - toga2-supply/src/pages/Shipments/view/components/ShipmentsCardTableForm/ShipmentsCardTableForm.tsx
+related:
+  - ../_underscore/architecture.md
+  - ../api2/architecture.md
+  - features/fulfill-and-ship.md
+---
+
+## Summary
+
+`toga2-supply` is the **React + Vite frontend** for TOGa Supply — warehouse fulfillment
+tooling (shipment selection, fulfill & ship against carrier APIs, NetSuite Item
+Fulfillment creation, label printing/reprinting). It is a pure frontend: all business
+logic lives in the 2.0 API (`api2` engine over `_underscore` models). It has **no
+backend code of its own** — `dependsOn: [api2]`.
+
+## Topology (dev/test setup)
+
+- The frontend runs **locally** on the developer machine (e.g.
+  `http://growrk.togasupply:5173`); it is not deployed to beta in this setup. Local
+  code edits take effect on reload.
+- It calls the **beta** API at `https://api.beta.togahub.com`. Backend (`_underscore`)
+  changes therefore require a **deploy to beta** before they are observable — a symptom
+  can look "unfixed" simply because the backend fix isn't deployed yet.
+- Client subdomain selects the tenant (e.g. `growrk.togasupply` → client GroWrk,
+  DB `Client_Growrk`).
+
+## Shared API client — `src/api/toga.ts`
+
+`togaApiRequest` resolves the API base from the hostname, auto-bootstraps auth
+(`/auth/public` / `/auth/refresh`), and **retries once on 401**. The recurring 401s
+seen at page load are this retry/refresh pattern (usually transient) — the real failure
+mode is a non-401 status (400/business error) carrying a message.
+
+Response envelope (2.0 API): `{ isSuccess, status, error, messages, data: { <route>:
+{ <method>: ... } } }`. Scripted-API results nest as `data.<routeCamel>.<methodName>`.
+
+## Route map
+
+| Route | Page | Purpose |
+|---|---|---|
+| `/shipment-items?internalId=<NS SO id>` | `ShipmentItemsPage` | select SO line items; the **only** place the SO syncs from NetSuite into Toga; stores selection in `localStorage("selectedItems")` |
+| `/edit-shipment?internalId=<id>` | `EditShipmentPage` → `EditShipmentForm` | serials, carrier, method → **Fulfill & Ship** |
+| `/shipments`, `/fulfilled-shipments` | `ShipmentsCardTableForm` | pending vs fulfilled views; reprint lives here |
+
+## Key decisions
+
+- Carrier dropdown filters to FEDEX/UPS carriers that have ≥1 account number.
+- Success/failure gating: a fulfillment is only "green" when the carrier returned a real
+  tracking number AND NetSuite returned a numeric internalId (`/^\d+$/`) — see the
+  fulfill-and-ship feature doc.
+- Browser print: the print dialog handles one file at a time and `window.print()` fires
+  once per session — hence the combined-PDF reprint design. Popups must be allowed
+  (label window is `window.open`).
+
+## Related docs
+
+- [Fulfill & Ship feature](features/fulfill-and-ship.md) — the end-to-end flow, bugs, gotchas.
+- [Carrier shipping labels (_underscore)](../_underscore/features/carrier-shipping-labels.md) — backend label + NetSuite mechanics.

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

@@ -0,0 +1,112 @@
+---
+title: Fulfill & Ship
+framework: "2.0"
+repo: toga2-supply
+project: TOGa Supply
+client: shared
+type: feature
+status: active
+updated: 2026-06-10
+owners: [mhammontree]
+files:
+  - toga2-supply/src/pages/ShipmentItems/view/ShipmentItemsPage.tsx
+  - toga2-supply/src/pages/EditShipment/view/EditShipmentPage.tsx
+  - toga2-supply/src/pages/EditShipment/view/components/forms/EditShipmentForm.tsx
+  - toga2-supply/src/pages/EditShipment/api/UpdateShipmentApi.ts
+  - toga2-supply/src/pages/Shipments/view/components/ShipmentsCardTableForm/ShipmentsCardTableForm.tsx
+  - toga2-supply/src/pages/Shipments/api/ShipmentsApi.ts
+  - _underscore/Model/Client/ItemFulfillment.php
+  - _underscore/Trait/Netsuite/ItemFulfillment.php
+  - _underscore/Component/Library/Carriers/Ups/Ups.php
+related:
+  - ../architecture.md
+  - ../../_underscore/features/carrier-shipping-labels.md
+  - ../../_underscore/features/recursive-item-fulfillments.md
+---
+
+## Summary
+
+Fulfill & Ship lets a warehouse user select sales-order line items, enter serials,
+pick a carrier/method, and in one action: create the Item Fulfillment records in Toga,
+buy a carrier label (UPS/FedEx), and create the NetSuite Item Fulfillment with the
+tracking number and label attached. Driven green end-to-end on beta (UPS, client
+GroWrk, June 2026); FedEx + UPS both need verification before prod.
+
+## How it works
+
+1. `/shipment-items` load: `checkIfSalesOrderExists(internalId)` (GET `/sales-orders`
+   by `c_netsuiteInternalSalesOrderId`); if missing →
+   `GET /sales-orders/syncNetsuiteSalesOrder` then `syncNetsuiteItemFulfillmentWithToga`.
+   **This is the only place the SO syncs from NetSuite into Toga.**
+2. `/edit-shipment` submit (`onFormSubmit("fulfillAndShip")` in `EditShipmentForm.tsx`):
+   - `saveShipment` → POST `/item-fulfillments`, `/tracking-numbers`,
+     `/item-fulfillment-packages`.
+   - `fulfillShipment` → GET `/item-fulfillments/upsShipmentApi` (or `fedexShipmentApi`)
+     for the label, then `saveShipmentToNetsuite` →
+     GET `/item-fulfillments/createNetsuiteItemFulfillment`.
+   - `handleShipmentDownload` opens the label PDF and triggers print.
+3. **Success gating**: `fulfillShipment` returns `{ success, error, data }` and requires
+   BOTH a real tracking number (no `error`) AND a numeric NetSuite internalId
+   (`/^\d+$/` — `createNetsuiteItemFulfillment` returns the numeric internalId on
+   success but an **error string** on failure). Both callers gate the success toaster
+   on `success`.
+4. The label `fileInternalId` is passed through `fulfillShipment` →
+   `saveShipmentToNetsuite` → `createNetsuiteItemFulfillment`, which attaches the label
+   to the IF **after** creating it (the IF doesn't exist yet when the label is bought).
+
+## Reprint (first pass — being reworked)
+
+Fulfilled-shipments view: multi-select shipments, merge each stored label into one
+multi-page PDF with `pdf-lib`, print once. **Superseded by the label-storage decision**
+(see the carrier-shipping-labels doc): labels will be stored as raw carrier GIFs and
+the combined PDF generated on demand — note `pdf-lib` cannot embed GIF, so generation
+likely moves to the backend.
+
+## Gotchas / known issues
+
+- **UPS test endpoint** (`wwwcie.ups.com`, debug mode) returns a constant tracking
+  number `1ZXXXXXXXXXXXXXXXX` + SAMPLE labels. On 2nd+ test runs this collides with the
+  `TrackingNumbers.number` UNIQUE index (surfaces mislabeled as "Labelary API error")
+  AND NetSuite File Cabinet's unique filename (`ShippingLabel_<tracking>.pdf`). Free
+  both between runs:
+  `UPDATE TrackingNumbers SET number = CONCAT(number,'-',id) WHERE number='1ZXXXXXXXXXXXXXXXX'`
+  and delete/rename the prior File Cabinet file. Never happens in prod.
+- **Address source mismatch**: `upsShipmentApi` reads ship-to from the **Sales Order**
+  (`SalesOrder.shipToAddressId`), NOT the address edited in the form (the IF's) — form
+  address edits never reach the carrier. Open decision: read the IF address instead.
+- **UPS address limits**: `AddressLine` max 35 chars/line; code currently sends
+  `line1 + ' ' + line2` as one line — should send a trimmed array (FedEx path already
+  does).
+- **Service codes are carrier-scoped**: UPS numeric (`03`=Ground, `01`=Next Day Air),
+  FedEx strings (`FEDEX_GROUND`), in `ShippingMethods.code`. Empty code → UPS 120500;
+  there is now a fast-fail guard.
+- **Serialized inventory needs a location**: a SO with no Warehouse Location makes
+  NetSuite reject the serial issue ("Invalid issueinventorynumber reference key").
+  Recommended hardening: always scope `getInventoryNumberFromSerialNumber` by location.
+- **EV-12 on POST /item-fulfillments** means the SO isn't synced into Toga yet — fire
+  `GET /sales-orders/syncNetsuiteSalesOrder?netsuiteInternalSalesOrderId=<id>`.
+- **Carrier on the NS IF defaults wrong**: `createNetsuiteItemFulfillment` doesn't set
+  carrier/method, so the IF can show FedEx while the tracking number is UPS. Open item.
+- Real carrier errors live in the client-logs `Api` table (DIRECTION `OUT`,
+  `hostname LIKE '%ups.com%'`, `responsePayload`).
+- React warning: `setState`-in-render in `ShipmentItemsTable.tsx` (~line 149,
+  `clearErrors` inside a `setRowsClicked` updater) — move out of the updater.
+
+## Remaining work
+
+- Label storage + reprint rework per the carrier-shipping-labels doc (raw GIF +
+  on-demand combined PDF).
+- Return-label flow: `returnTrackingNumberId` (nullable) on `ItemFulfillmentItemUnits`;
+  "needs return label" checkbox; return-address editable combo ("Rolodex pattern" of
+  client locations, overridable, validated); "return label" text on return pages of the
+  combined PDF.
+- Address-source decision, UPS 35-char hardening, location-scoped inventory lookup,
+  carrier/method on the NS IF, responsiveness per Figma, FedEx + UPS end-to-end
+  verification before prod.
+
+## Client variations
+
+None in the flow itself — but the NetSuite trait is composed into **client-specific**
+model subclasses (e.g. `_Model_Growrk_ItemFulfillment uses _Trait_Netsuite_ItemFulfillment`),
+not the base `_Model_Client_ItemFulfillment`. Tested with GroWrk; UPS support was built
+for Compass and is not yet in prod.

package/knowledge/INDEX.md

@@ -9,10 +9,11 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 
 ## 2.0 framework
 
-- **_underscore** (_Underscore) _(framework core)_ — 2 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
+- **_underscore** (_Underscore) _(framework core)_ — 3 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
 - **worker2** (Worker) — 3 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
 - **api2** (API) — 1 doc(s) → [2.0/apps/api2/INDEX.md](2.0/apps/api2/INDEX.md)
 - **dbchanges2** (Database Changes) _(framework core)_ — 1 doc(s) → [2.0/apps/dbchanges2/INDEX.md](2.0/apps/dbchanges2/INDEX.md)
+- **toga2-supply** (TOGa Supply) — 2 doc(s) → [2.0/apps/toga2-supply/INDEX.md](2.0/apps/toga2-supply/INDEX.md)
 
 ## Clients
 

package/knowledge/registry.json

@@ -4,5 +4,6 @@
   { "repo": "api2",        "project": "API",         "framework": "2.0", "role": "app",  "dependsOn": [] },
   { "repo": "dbchanges2",  "project": "Database Changes", "framework": "2.0", "role": "core", "dependsOn": [] },
   { "repo": "library",     "project": "Library",     "framework": "1.0", "role": "core", "dependsOn": [] },
-  { "repo": "worker",      "project": "Worker",      "framework": "1.0", "role": "app",  "dependsOn": [] }
+  { "repo": "worker",      "project": "Worker",      "framework": "1.0", "role": "app",  "dependsOn": [] },
+  { "repo": "toga2-supply", "project": "TOGa Supply", "framework": "2.0", "role": "app",  "dependsOn": ["api2"] }
 ]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toga-ai",
-  "version": "1.0.31",
+  "version": "1.0.33",
   "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/scripts/install.js

@@ -661,13 +661,28 @@ function main() {
   const ok = mergeSettings(claudeDir, harnessDir);
   console.log('  ' + (ok ? '✓' : '✗') + ' Hooks     (' + hooksCount + ' scripts in .claude/hooks/toga/, settings.json merged)');
 
-  // MCP example — skip if already present
+  // Contexts — mode context files (dev/research/review), update if changed
+  const contextsSrc = path.join(harnessDir, 'contexts');
+  const contextsDest = path.join(claudeDir, 'contexts', 'toga');
+  if (fs.existsSync(contextsSrc)) {
+    let contextsStats = { added: 0, updated: 0, unchanged: 0 };
+    try { contextsStats = copyDir(contextsSrc, contextsDest, { updateIfChanged: true }); }
+    catch (e) { errors.push('contexts: ' + e.message); }
+    console.log('  ✓ Contexts  (' + countMd(contextsDest) + '): ' + fmtStats(contextsStats));
+  }
+
+  // MCP example — update if changed so teammates get new server configs
   const mcpSrc = path.join(harnessDir, 'mcp-configs', 'mcp-servers.json');
   const mcpDest = path.join(claudeDir, 'mcp-servers.example.json');
-  if (fs.existsSync(mcpSrc) && !fs.existsSync(mcpDest)) {
-    try { fs.copyFileSync(mcpSrc, mcpDest); }
-    catch (e) { errors.push('mcp: ' + e.message); }
-    console.log('  ✓ MCP       (.claude/mcp-servers.example.json — merge into .mcp.json to enable)');
+  if (fs.existsSync(mcpSrc)) {
+    try {
+      const firstInstall = !fs.existsSync(mcpDest);
+      const incoming = fs.readFileSync(mcpSrc);
+      if (firstInstall || !incoming.equals(fs.readFileSync(mcpDest))) {
+        fs.copyFileSync(mcpSrc, mcpDest);
+        console.log('  ✓ MCP       (.claude/mcp-servers.example.json ' + (firstInstall ? 'created' : 'updated') + ' — merge into .mcp.json to enable)');
+      }
+    } catch (e) { errors.push('mcp: ' + e.message); }
   }
 
   // Knowledge — git repo if available (has team-captured docs), else npm bundle
@@ -697,6 +712,26 @@ function main() {
   }
   console.log('  ✓ Knowledge (' + countMd(knowledgeDest) + ' docs): ' + fmtStats(knowledgeStats));
 
+  // registry.json — the repo↔project↔framework map every skill depends on.
+  // Force-sync explicitly from the newest source (git if pulled, else bundle) so a
+  // partial knowledge copy can never leave a machine without/with a stale registry.
+  const registrySrc = path.join(knowledgeDir, 'knowledge', 'registry.json');
+  const registryDest = path.join(knowledgeDest, 'registry.json');
+  if (fs.existsSync(registrySrc)) {
+    try {
+      fs.copyFileSync(registrySrc, registryDest);
+      let repoCount = 0;
+      try {
+        const reg = JSON.parse(fs.readFileSync(registryDest, 'utf8'));
+        repoCount = Array.isArray(reg) ? reg.length : 0;
+      } catch (e) {}
+      console.log('  ✓ Registry  (' + repoCount + ' repos): synced from ' + (knowledgeDir !== PACKAGE_ROOT ? 'git repo' : 'npm bundle'));
+    } catch (e) { errors.push('registry.json: ' + e.message); }
+  } else {
+    errors.push('registry.json: missing from source ' + registrySrc);
+    console.log('  ✗ Registry  MISSING from source — kickoff will not work. Re-run: npm cache clean --force && npx toga-ai@latest');
+  }
+
   // CLAUDE.md
   const action = updateClaudeMd(projectRoot, skillNames, harnessDir, 'npm bundle v' + bundleVersion);
   console.log('  ✓ CLAUDE.md ' + action);

package/skills/kickoff/SKILL.md

@@ -5,7 +5,18 @@ description: Start-of-session context loader for TOGA Technology projects. Run t
 
 # Kickoff — prime a coding session from the team knowledge base
 
-## Step 0 — Auto-update check (runs before anything else)
+## Arguments — text passed after `/kickoff` never skips any step
+
+`/kickoff` may be invoked with trailing text (e.g. `/kickoff worker2 backend fix for Compass`).
+That text is the developer's description of today's work — it is **not** permission to
+shortcut the flow.
+
+- **Step 0 (auto-update check) ALWAYS runs first**, with or without arguments.
+- Use the argument text to **pre-fill answers** to the Step 2 interview (framework, layer,
+  repo, client, task). Only ask about whatever is still missing or ambiguous.
+- Never treat the argument as an instruction to start coding before Steps 0–5 complete.
+
+## Step 0 — Auto-update check (runs before anything else, even with arguments)
 
 Before loading any context, check whether the installed harness is up to date:
 
@@ -20,17 +31,33 @@ LATEST=$(node -e "const {execSync}=require('child_process');try{process.stdout.w
 
 **If `INSTALLED` equals `LATEST`** — already up to date. Continue to Step 1.
 
-**If `INSTALLED` differs from `LATEST`** — auto-upgrade now, then continue:
+**If `INSTALLED` differs from `LATEST`** — auto-upgrade now, then **verify** before continuing:
 
 ```bash
 npx toga-ai@latest
 ```
 
-Tell the developer:
-> "Updated toga-ai from v`INSTALLED` → v`LATEST`. Skills, agents, and rules refreshed."
+After the upgrade, re-read the version file to confirm it actually updated — npx can
+serve a stale cached package (common on Windows), in which case the installer ran but
+installed the old version again:
+
+```bash
+NOW=$(cat .claude/toga-ai.version 2>/dev/null || echo "unknown")
+```
 
-If the upgrade fails, warn and continue — a stale install beats a blocked session:
-> "⚠ Auto-update to v`LATEST` failed. Run `npx toga-ai@latest` manually when convenient."
+- **If `NOW` equals `LATEST`** — success. Tell the developer:
+  > "Updated toga-ai from v`INSTALLED` → v`LATEST`. Skills, agents, knowledge, and registry refreshed."
+- **If `NOW` still differs from `LATEST`** — stale npx cache. Retry once with a clean cache:
+  ```bash
+  npm cache clean --force && npx toga-ai@latest
+  ```
+  Re-read the version file again. If it now equals `LATEST`, report success as above.
+- **If still stale after the cache-clean retry, or the upgrade command failed** — warn and
+  continue; a stale install beats a blocked session:
+  > "⚠ Auto-update to v`LATEST` failed (still on v`NOW`). Run `npm cache clean --force && npx toga-ai@latest` manually when convenient."
+
+Never report the update as done based on the command exiting cleanly — only the version
+file equaling `LATEST` counts as success.