toga-ai 1.0.78 → 1.0.80

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

@@ -4,5 +4,6 @@
 |-----|---------|-------|
 | [_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 |
+| [Client Email Template Sending](features/email-template-sending.md) | `_Model_Client_EmailTemplate` sends a stored, client-defined email template by UUID. | _underscore/Model/Client/EmailTemplate.php, _underscore/Model/Client/EmailTemplateOutgoingEmailAddress.php, _underscore/Email.php |
 | [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 |
 | [Tracking-Number Bridge Migration (ASN / Item Fulfillment / Item Receipt)](features/tracking-number-bridges.md) | Shipment tracking numbers used to live as **scalar FK columns** (`trackingNumberId`, `returnTrackingNumberId`) directly on the lowest-level "unit"/"item" tables | _underscore/Model/Client/AdvanceShippingNoticeItemUnit.php, _underscore/Model/Client/AdvanceShippingNoticeItemUnits/TrackingNumber.php, _underscore/Model/Client/ItemFulfillmentItemUnits/TrackingNumber.php, _underscore/Model/Client/ItemFulfillment.php, _underscore/Model/Prudential/AdvanceShippingNotice.php, _underscore/Model/Compass/AdvanceShippingNotice.php, _underscore/Trait/Netsuite/ItemFulfillment.php, api2/Component/Api/Cxml/Cxml.php, dbchanges2/Client/2026-06-10 - TrackingNumberBridges.sql, dbchanges2/Core/2026-06-10 - TrackingNumberBridges.sql |

package/knowledge/2.0/apps/_underscore/features/email-template-sending.md

@@ -0,0 +1,88 @@
+---
+title: Client Email Template Sending
+framework: "2.0"
+repo: _underscore
+project: _Underscore
+client: shared
+type: feature
+status: active
+updated: 2026-06-15
+owners: ["jcardinal"]
+files:
+  - _underscore/Model/Client/EmailTemplate.php
+  - _underscore/Model/Client/EmailTemplateOutgoingEmailAddress.php
+  - _underscore/Email.php
+related: []
+---
+
+## Summary
+
+`_Model_Client_EmailTemplate` sends a stored, client-defined email template by UUID. It
+loads the template from the client DB (`EmailTemplates` table), merges any template-stored
+recipient addresses, substitutes `{variable}` placeholders in the subject and body, and
+sends via `_Email`. The only client-specific input the send actually needs is the
+**client identifier** (used to scope the outgoing mail via `_Email::setClientIdentifier()`).
+
+## Key files / entry points
+
+- `_underscore/Model/Client/EmailTemplate.php` — the model. Three relevant methods:
+  - **`sendEmail(&$api, $uuid, $to, $cc, $bcc, ...$args): bool`** — the scripted-API entry
+    point. First param is `&$api` per the Record Script contract (see backend-php standard,
+    *Record Scripts*). The only thing it uses from `$api` is `$api->client->clientIdentifier`.
+  - **`send(string $clientIdentifier, $uuid, $to, $cc, $bcc, ...$args): bool`** — the
+    non-API entry point. Caller passes the client identifier directly; no `$api` object.
+  - **`dispatch(string $clientIdentifier, ...): bool`** (private) — the shared body both
+    entry points call. Holds all the real logic.
+- `_Model_Client_EmailTemplateOutgoingEmailAddress` — per-template stored TO/CC/BCC
+  addresses (`toCcBcc` enum), merged into the caller-supplied recipients.
+- `_underscore/Email.php` — `_Email` requires a non-empty `clientIdentifier` (throws
+  `clientIdentifier is required` otherwise) and uses it as the CloudWatch log stream name.
+
+## How it works
+
+1. Load the template by `uuid`; return `false` immediately if `!isActive`.
+2. Search `EmailTemplateOutgoingEmailAddress` for the template and append each stored
+   address to `$to` / `$cc` / `$bcc` by its `toCcBcc` value.
+3. Build `_Email`, set the client identifier, add recipients, set From from the template's
+   `sendFromEmailAddress` / `sendFromName`.
+4. Replace `{key}` placeholders in subject and body from the `$args` variadic map
+   (`replaceTemplateVariables`), then `send()`.
+
+Both `sendEmail()` and `send()` are thin wrappers that forward to `dispatch()`, so the API
+and non-API paths run identical code — no behavioral drift between them.
+
+## Data model
+
+- `EmailTemplates` (client DB): `uuid`, `isActive`, `sendFromEmailAddress`, `sendFromName`,
+  `priority`, `subject`, `body`.
+- `EmailTemplateOutgoingEmailAddress` (client DB): `emailTemplateId`, `emailAddress`,
+  `toCcBcc` (`TO`/`CC`/`BCC`).
+
+## Client variations
+
+The model is shared; client-specific senders pass their own identifier. Workers use a class
+constant (e.g. `self::CLIENT_IDENTIFIER`); model/interceptor code that already has an `$api`
+can keep using `sendEmail($api, ...)`.
+
+## Gotchas / known issues
+
+- **Use `send()` from any non-API context (workers, cron, internal code).** Before
+  2026-06-15 the only entry point was `sendEmail(&$api, ...)`, so callers with no API
+  context faked one: `$api = (object)['client' => (object)['clientIdentifier' => …]]`.
+  That hack is obsolete — pass the identifier to `send()` instead.
+- **`sendEmail()`'s signature is load-bearing for scripted APIs** — the Record Script engine
+  (`api2/Component/Api/V2/V2.php`, ~line 3594) calls the method with `api` as a named
+  argument, so the first param must stay `&$api`. Do not "clean it up" by removing it.
+- `_Email::send()` throws if the client identifier is empty — `send('')` will fail at send
+  time, not at call time.
+
+## Change history
+
+- 2026-06-15 — Added non-API `send(clientIdentifier, …)` entry point + private `dispatch()`;
+  `sendEmail(&$api, …)` kept unchanged as a wrapper for backward compatibility. Migrated the
+  `worker2` Compass Report and AI-BDR NetSuite callers off the fake-`$api` hack. (jcardinal)
+
+## Related docs
+
+- `2.0/standards/backend-php.md` — *Record Scripts* (the `&$api` contract).
+- `2.0/apps/api2/architecture.md` — scripted-API dispatch in `V2.php`.

package/knowledge/2.0/standards/backend-php.md

@@ -5,7 +5,7 @@ project: _Underscore
 client: shared
 type: standard
 status: active
-updated: 2026-06-08
+updated: 2026-06-15
 owners: [jcardinal]
 files: []
 related:
@@ -425,6 +425,13 @@ if ($user->load()) { /* found */ }
 
 * Use tabs for indentation, not spaces.
 
+#### **Line Endings**
+
+* The 2.0 repos have **no `.gitattributes`** and contain a **mix of LF and CRLF files** — there is no single repo-wide line ending. Core files (e.g. `Model.php`, `Loader.php`, `Email.php`) are CRLF; many others (e.g. `Model/Client/EmailTemplate.php`) are LF.
+* **Preserve a file's existing line ending when you edit it.** Do not let an editor or tool silently convert the whole file (a common LF→CRLF flip on Windows).
+* A whole-file ending flip turns a one-line change into a full-file rewrite in `git diff`, burying the real change, breaking `git blame`, and inviting merge conflicts.
+* **Check before committing:** if `git diff --stat` shows a tiny edit as a near-total rewrite, the endings flipped. Restore them — e.g. for an LF file: `tr -d '\r' < file > file.tmp && mv file.tmp file` — then re-stage.
+
 #### **Braces**
 
 * Opening braces for classes, methods and control structures (`if`, `else`, `for`, `while`, etc.) should go on the same line.

package/knowledge/INDEX.md

@@ -11,7 +11,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 
 ## 2.0 framework
 
-- **_underscore** (_Underscore) _(framework core)_ — 5 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
+- **_underscore** (_Underscore) _(framework core)_ — 6 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
 - **worker2** (Worker) — 6 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)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toga-ai",
-  "version": "1.0.78",
+  "version": "1.0.80",
   "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/kickoff/SKILL.md

@@ -5,16 +5,36 @@ description: Start-of-session context loader for TOGA Technology projects. Run t
 
 # Kickoff — prime a coding session from the team knowledge base
 
+> ## 🛑 STOP — THIS IS A BLOCKING GATE. READ BEFORE DOING ANYTHING ELSE.
+>
+> When `/kickoff` is invoked you **MUST** complete Steps 0–6 of this skill **before**
+> any other tool call — no `Read`, `Grep`, `Glob`, `Edit`, `Write`, `Bash`, no agent
+> spawn, no investigation, no answering the developer's question. Priming comes first,
+> **always**.
+>
+> **Trailing text after `/kickoff` is NEVER a reason to skip priming.** A long, detailed
+> paragraph describing a specific task (file paths, line numbers, a design question) is
+> *still just the Step 2 task description* — it is input to the interview, **not**
+> permission to start working. The more detailed and actionable the request looks, the
+> more tempting it is to dive in — **resist that.** If you find yourself about to open a
+> file the developer named before you have loaded the knowledge base, you are violating
+> this gate. Stop and run Steps 0–6 first.
+>
+> Only after Step 5's "primed and ready" summary (and Step 6's plan, for non-trivial work)
+> may you touch the task itself.
+
 ## 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.
+`/kickoff` may be invoked with trailing text (e.g. `/kickoff worker2 backend fix for Compass`),
+including a long, specific paragraph naming exact files, line numbers, and a concrete
+change. That text is the developer's description of today's work — it is **not** permission
+to shortcut the flow, no matter how actionable it looks.
 
 - **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–6 complete.
+- Never treat the argument as an instruction to start coding — or even to start *reading
+  the named files* — before Steps 0–6 complete. Investigation IS work; it waits for priming.
 
 ## Step 0 — Auto-update check (runs before anything else, even with arguments)