toga-ai 1.0.121 → 1.0.123

package/knowledge/1.0/apps/worker/INDEX.md

@@ -3,7 +3,8 @@
 | Doc | Summary | Files |
 |-----|---------|-------|
 | [Worker (1.0 Framework) Architecture](architecture.md) | `worker` is the legacy (**1.0** `App_` framework) **background-job tier**. | worker/index.php, worker/_/app/framework.php, worker/crons/, worker/schedules/, worker/ebs/cron.worker.php, worker/.ebextensions/035_cron.worker.config |
-| [Compass Partial In-Transit & Delivered Emails (per package)](features/compass-partial-in-transit-delivered-emails.md) | Compass USA and Compass Canada send a **per-package** in-transit email (and a matching delivered email) instead of one email listing the whole order. | worker/crons/toga2/compass/update_salesorder_status_from_odp.php, worker/crons/toga2/compass/workflow/test_partial_in_transit_email.php, worker/crons/toga2/compasscanada/workflow/3_update_salesorder_status_from_grand_and_toy.php, worker/crons/toga2/compasscanada/workflow/test_partial_in_transit_email.php |
+| [Compass MA Sales Order Exception Report](features/compass-ma-sales-order-exception-report.md) | A worker cron that emails operations the "Compass Refresh Exception Report" — Compass `MA%` sales orders whose corresponding Office Depot (ODP) sales order has | worker/crons/toga2/compass/workflow/7_generate_ma_sales_order_exception_report.php |
+| [Compass Partial In-Transit & Delivered Emails (per package)](features/compass-partial-in-transit-delivered-emails.md) | Compass USA and Compass Canada send a **per-package** in-transit email (and a matching delivered email) instead of one email listing the whole order. | worker/crons/toga2/compass/update_salesorder_status_from_odp.php, worker/crons/toga2/compasscanada/workflow/3_update_salesorder_status_from_grand_and_toy.php |
 | [Forecast2 ↔ NetSuite Reconciliation & Trueup Tooling](features/forecast2-netsuite-reconciliation.md) | CLI tools to **audit** and **repair** drift between the production `Forecast` DB (core2) and NetSuite. | test/@dave/reconcile_netsuite_totals.php, test/@dave/analyze_netsuite_forecast_diff.php, test/@dave/trueup_sales.php, test/@dave/trueup_open_orders.php, test/@dave/trueup_opportunities.php, test/@dave/probe_sales_gap_direct.php, worker/crons/toga2/forecast2/common_import_sales_from_netsuite.php |
 | [NetSuite → TOGa Supply Per-Client Sync (thin wrappers)](features/netsuite-togasupply-per-client-sync.md) | Syncs NetSuite transactions (sales orders, purchase orders, invoices, item receipts, item fulfillments, inventory adjustments) into each TOGa Supply (2.0) clien | worker/crons/toga2/netsuite/common_sync_togasupply.php, worker/crons/toga2/netsuite/sync_togasupply_canon.php, worker/schedules/cron.worker.sync.json, dbchanges2/_modules/netsuite/2026-04-01 - Parameters.sql |
 | [Prudential: Send Shipments for the Day report (daily cron)](features/send-shipments-for-the-day.md) | Daily cron (9:00 PM) that emails Prudential and Dell stakeholders an Excel report of all devices shipped that day, including tracking number, serial number, emp | worker/crons/notifications/reports/send_shipments_for_the_day.php |

package/knowledge/1.0/apps/worker/features/compass-ma-sales-order-exception-report.md

@@ -0,0 +1,82 @@
+---
+title: Compass MA Sales Order Exception Report
+framework: "1.0"
+repo: worker
+project: Worker
+client: compass-usa
+type: feature
+status: active
+updated: 2026-06-18
+owners: ["bala"]
+files:
+  - worker/crons/toga2/compass/workflow/7_generate_ma_sales_order_exception_report.php
+related: []
+---
+
+## Summary
+A worker cron that emails operations the "Compass Refresh Exception Report" — Compass `MA%`
+sales orders whose corresponding Office Depot (ODP) sales order has **not** been created in
+NetSuite yet. It is a catch-the-stragglers report: orders that should have flowed to NetSuite
+but haven't. Runs against the Compass client DB (`db_prod_compass` / `Client_Compass`).
+
+## Key files / entry points
+- `worker/crons/toga2/compass/workflow/7_generate_ma_sales_order_exception_report.php` — the
+  whole job: one main SELECT, a per-row NetSuite recheck, and a PhpSpreadsheet Excel email.
+
+## How it works
+1. **Main query** walks a two-hop bridge chain to connect the customer order to the vendor order:
+   Compass SO (`number LIKE 'MA%'`) → `SalesOrders_PurchaseOrders` → Compass PO →
+   `PurchaseOrders_SalesOrders` → **ODP SO** (`customerId = OFFICE_DEPOT`) →
+   `SalesOrders_PurchaseOrders` → ODP PO. Note the two bridge tables are used in **opposite
+   directions** at each hop — `SalesOrders_PurchaseOrders` for SO→PO, `PurchaseOrders_SalesOrders`
+   for PO→SO. It also inner-joins the ODP SO's address, state, items, item→PO-item bridge, PO
+   items, and vendor items — so a row with any of those missing silently drops out.
+2. **Filter:** `MA%` Compass SO, ODP SO `customerId = App_Client_Compass::CUSTOMER_ID__OFFICE_DEPOT`
+   (= 1), and `OfficeDepotSalesOrders.c_netsuiteInternalSalesOrderId IS NULL`.
+3. **Per-row NetSuite recheck:** for each surviving row it looks for an **Agilant**-customer
+   (`CUSTOMER_ID__AGILANT` = 3) sales order tied to that ODP PO number. If found → it back-fills
+   `c_netsuiteInternalSalesOrderId` on the ODP SO and skips the row (drops it off the report
+   permanently). If not found → it writes the row to the Excel.
+4. Emails the workbook to operations only if at least one data row was written.
+
+## Data model
+- `Client_Compass.SalesOrders` — the ODP sales order is the one keyed on (`id AS salesOrderId`,
+  `customerId = 1` Office Depot). Relevant columns: `c_netsuiteInternalSalesOrderId` (NULL until
+  the order exists in NetSuite) and `salesOrderStageId`.
+- `Client_Compass.SalesOrderStages` — `5 = Pending Billing`, `6 = Pending Billing/Partially
+  Fulfilled`, `7 = Billed`, `8 = Canceled`, `9 = Closed`.
+- Bridges: `SalesOrders_PurchaseOrders` (salesOrderId, purchaseOrderId) and
+  `PurchaseOrders_SalesOrders` (purchaseOrderId, salesOrderId) — distinct tables, distinct
+  directions.
+
+## Client variations
+Compass USA only — this is a Compass-specific integration cron.
+
+## Gotchas / known issues
+- **Two removal levers, and only one used to exist.** Historically the *only* way an order left
+  the report was `c_netsuiteInternalSalesOrderId` becoming non-NULL (set by the per-row recheck
+  when the NetSuite order is found). An order **closed/canceled on Office Depot's end** never gets
+  a NetSuite order, so it never gets that id, so it stuck on the report forever. The fix (2026-06)
+  added a **stage-based exclusion** so canceling/closing the ODP SO removes it.
+- **To remove an order, mark the OFFICE DEPOT sales order — not the Compass SO.** The query
+  filters on `OfficeDepotSalesOrders.salesOrderStageId`; the Compass SO's stage is never read.
+  Setting the Compass `MA%` order's stage does nothing.
+- **NULL-safe stage filter is mandatory.** Active orders normally have `salesOrderStageId = NULL`.
+  In SQL `NULL NOT IN (8, 9)` evaluates to *unknown* (not true), so a bare
+  `salesOrderStageId NOT IN (8, 9)` would drop **every NULL-stage order** — i.e. almost the whole
+  report. The condition must be `(salesOrderStageId IS NULL OR salesOrderStageId NOT IN (8, 9))`,
+  and it must be parenthesized because `AND` binds tighter than `OR`.
+- **Don't fake the NetSuite id to hide an order.** Writing a bogus `c_netsuiteInternalSalesOrderId`
+  removes it from the report but corrupts the field for anyone who reads it later. Use the stage
+  lever instead.
+- `$inProduction = true` switches the DB link to `db_prod_compass`; set false to test against
+  `db_beta_compass`.
+
+## Change history
+- 2026-06-18 — Added stage-based exclusion so orders closed/canceled on ODP's end drop off the
+  report: `(salesOrderStageId IS NULL OR salesOrderStageId NOT IN (8, 9))` in the main query.
+  Removing specific stuck orders is then a data change (set the ODP SO's `salesOrderStageId` to
+  8/9), not a code change. (bala)
+
+## Related docs
+- [Compass USA profile](../../../clients/compass-usa/profile.md)

package/knowledge/1.0/apps/worker/features/compass-partial-in-transit-delivered-emails.md

@@ -10,9 +10,7 @@ updated: 2026-06-18
 owners: ["bala"]
 files:
   - worker/crons/toga2/compass/update_salesorder_status_from_odp.php
-  - worker/crons/toga2/compass/workflow/test_partial_in_transit_email.php
   - worker/crons/toga2/compasscanada/workflow/3_update_salesorder_status_from_grand_and_toy.php
-  - worker/crons/toga2/compasscanada/workflow/test_partial_in_transit_email.php
 related: []
 ---
 
@@ -30,8 +28,6 @@ and earlier packages). The dynamic HTML is injected into a stored `EmailTemplate
 - `worker/crons/toga2/compass/update_salesorder_status_from_odp.php` — Compass USA prod cron.
 - `worker/crons/toga2/compasscanada/workflow/3_update_salesorder_status_from_grand_and_toy.php`
   — Compass Canada prod cron.
-- `*/workflow/test_partial_in_transit_email.php` — read-only prod test scripts for each client
-  (email goes only to a test recipient, no DB writes). Use these to preview rendering.
 - Shared helper set in each cron: `getOrderFulfillmentData`, `buildItemRowsHtml`,
   `buildSectionHeaderHtml`, `buildPackageBlockHtml`, `buildTrackingUrl`, `buildOrderItemsHtml`.
 
@@ -106,14 +102,13 @@ the tracking number as emailed (it retries next run).
   `getOrderFulfillmentData` — same query as Compass USA. Canada was originally on the ASN chain
   because it had **zero `ItemFulfillmentItems`**; if that line-bridge data is not populated for a
   Canada order, `getOrderFulfillmentData` returns no packages and the cron falls back to the
-  full email. Verify line-bridge data exists for Canada before relying on the partial path.
+  full email.
 - **Line bridge is moving-forward only** — it began populating ~2026-06-12; pre-cutoff tracking
   numbers are intentionally out of scope (driving-query date cutoff).
 - The driving query still uses the ASN chain (to find shipped orders + tracking) for **both**
   clients — that is correct and unrelated to the package-contents source.
-- Test scripts only ever email a test recipient and never write `c_dtInTransitEmailSent`.
-- **Not yet deployed.** These crons depend on the api2 POST scripted-API change and the
-  `RecordScripts`/`AclRecordScripts` registration (prod done, beta pending) — see related docs.
+- **Not yet deployed.** These crons depend on the api2 POST scripted-API change and its
+  `RecordScripts`/`AclRecordScripts` registration — see related docs.
 
 ## Change history
 

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

@@ -87,7 +87,7 @@ can keep using `sendEmail($api, ...)`.
   (previously the inactive case returned `false` and an SMTP failure was swallowed entirely).
   Any fire-and-forget caller now propagates that exception, which is intended (so an email is
   never silently marked as sent). Blast radius is every client, including the Compass/Quad
-  `SalesOrder`/`ApprovalDecision` order-placed emails — verify on beta before shipping.
+  `SalesOrder`/`ApprovalDecision` order-placed emails.
 
 ## Change history
 

package/knowledge/2.0/apps/api2/features/scripted-api-post-body-args.md

@@ -65,13 +65,9 @@ None — this is engine behavior. Per-client access is controlled by `AclRecordS
 - **Normal CRUD is unaffected.** The POST scripted block only fires when a POST Record Script
   is registered for the route; otherwise the request falls through to the usual create path
   (`if (!$isUsingScriptedCall && empty($routePairs))` / `locateRecord`).
-- **Registration is environment-specific.** The `RecordScripts` (Core) + `AclRecordScripts`
-  (client) rows must exist in every environment the API reads. As of this writing they were
-  run in **prod** for the email `sendEmail` script (Core + Client_Compass + Client_CompassCanada);
-  **beta still needs them** before the POST path dispatches there.
-- **Deploys with `_underscore`.** api2 pulls `_underscore` at deploy; `http://api2` and
-  `api.beta.togahub.com` resolve to deployed boxes (`/var/app/current`), not a local checkout —
-  so testing the change requires deploying it, not just editing locally.
+- **Registration is per-environment.** The `RecordScripts` (Core) + `AclRecordScripts`
+  (client) rows must exist in every environment the API reads; a missing POST `RecordScripts`
+  row means the POST path silently falls through to normal CRUD.
 - **CI commit policy.** Subject must be `TRUE-<ticket>: <Subject>` (≤80 chars, capitalized,
   imperative, no trailing period, more than one word).
 

package/knowledge/INDEX.md

@@ -5,7 +5,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 ## 1.0 framework
 
 - **library** (Library) _(framework core)_ — 4 doc(s) → [1.0/apps/library/INDEX.md](1.0/apps/library/INDEX.md)
-- **worker** (Worker) — 7 doc(s) → [1.0/apps/worker/INDEX.md](1.0/apps/worker/INDEX.md)
+- **worker** (Worker) — 9 doc(s) → [1.0/apps/worker/INDEX.md](1.0/apps/worker/INDEX.md)
 - **togadesk** (TOGa Desk) — 7 doc(s) → [1.0/apps/togadesk/INDEX.md](1.0/apps/togadesk/INDEX.md)
 - **togaview** (TOGa View) — 5 doc(s) → [1.0/apps/togaview/INDEX.md](1.0/apps/togaview/INDEX.md)
 - **webhook** (Webhook) — 1 doc(s) → [1.0/apps/webhook/INDEX.md](1.0/apps/webhook/INDEX.md)
@@ -29,6 +29,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 ## standalone framework
 
 - **togatech** (TOGA Technology Website) — 1 doc(s) → [standalone/apps/togatech/INDEX.md](standalone/apps/togatech/INDEX.md)
+- **forward** (Forwarder) — 2 doc(s) → [standalone/apps/forward/INDEX.md](standalone/apps/forward/INDEX.md)
 
 ## Clients
 

package/knowledge/registry.json

@@ -1,21 +1,156 @@
 [
-  { "repo": "_underscore", "project": "_Underscore", "framework": "2.0", "role": "core", "dependsOn": [] },
-  { "repo": "worker2",     "project": "Worker",      "framework": "2.0", "role": "app",  "dependsOn": [] },
-  { "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": "toga2-supply", "project": "TOGa Supply", "framework": "2.0", "role": "app",  "dependsOn": ["api2"] },
-  { "repo": "saml",        "project": "SAML SSO Gateway", "framework": "2.0", "role": "app",  "dependsOn": [] },
-  { "repo": "toga2-view",  "project": "TOGa View Frontend", "framework": "2.0", "role": "app",  "dependsOn": ["api2"] },
-  { "repo": "togadesk",    "project": "TOGa Desk",   "framework": "1.0", "role": "app",  "dependsOn": [] },
-  { "repo": "togaview",    "project": "TOGa View",   "framework": "1.0", "role": "app",  "dependsOn": [] },
-  { "repo": "toga2-hub",   "project": "TOGa Hub",    "framework": "2.0", "role": "app",  "dependsOn": ["api2"] },
-  { "repo": "togatech",    "project": "TOGA Technology Website", "framework": "standalone", "role": "app", "dependsOn": [] },
-  { "repo": "webhook",     "project": "Webhook",     "framework": "1.0", "role": "app",  "dependsOn": ["library"] },
-  { "repo": "walmarttechservices", "project": "Walmart Tech Services", "framework": "1.0", "role": "app", "dependsOn": ["library"] },
-  { "repo": "talos",       "project": "TOGa IQ",      "framework": "2.0", "role": "app", "dependsOn": [], "language": "python" },
-  { "repo": "test",        "project": "Test",        "framework": "1.0", "role": "app",  "dependsOn": ["library"] },
-  { "repo": "voice-to-voice", "project": "TOGa Voice", "framework": "2.0", "role": "app", "dependsOn": [], "language": "python" },
-  { "repo": "ai-bdr",      "project": "AI-BDR",      "framework": "2.0", "role": "app", "dependsOn": [] }
+  {
+    "repo": "_underscore",
+    "project": "_Underscore",
+    "framework": "2.0",
+    "role": "core",
+    "dependsOn": []
+  },
+  {
+    "repo": "worker2",
+    "project": "Worker",
+    "framework": "2.0",
+    "role": "app",
+    "dependsOn": []
+  },
+  {
+    "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": "toga2-supply",
+    "project": "TOGa Supply",
+    "framework": "2.0",
+    "role": "app",
+    "dependsOn": [
+      "api2"
+    ]
+  },
+  {
+    "repo": "saml",
+    "project": "SAML SSO Gateway",
+    "framework": "2.0",
+    "role": "app",
+    "dependsOn": []
+  },
+  {
+    "repo": "toga2-view",
+    "project": "TOGa View Frontend",
+    "framework": "2.0",
+    "role": "app",
+    "dependsOn": [
+      "api2"
+    ]
+  },
+  {
+    "repo": "togadesk",
+    "project": "TOGa Desk",
+    "framework": "1.0",
+    "role": "app",
+    "dependsOn": []
+  },
+  {
+    "repo": "togaview",
+    "project": "TOGa View",
+    "framework": "1.0",
+    "role": "app",
+    "dependsOn": []
+  },
+  {
+    "repo": "toga2-hub",
+    "project": "TOGa Hub",
+    "framework": "2.0",
+    "role": "app",
+    "dependsOn": [
+      "api2"
+    ]
+  },
+  {
+    "repo": "togatech",
+    "project": "TOGA Technology Website",
+    "framework": "standalone",
+    "role": "app",
+    "dependsOn": []
+  },
+  {
+    "repo": "webhook",
+    "project": "Webhook",
+    "framework": "1.0",
+    "role": "app",
+    "dependsOn": [
+      "library"
+    ]
+  },
+  {
+    "repo": "walmarttechservices",
+    "project": "Walmart Tech Services",
+    "framework": "1.0",
+    "role": "app",
+    "dependsOn": [
+      "library"
+    ]
+  },
+  {
+    "repo": "talos",
+    "project": "TOGa IQ",
+    "framework": "2.0",
+    "role": "app",
+    "dependsOn": [],
+    "language": "python"
+  },
+  {
+    "repo": "test",
+    "project": "Test",
+    "framework": "1.0",
+    "role": "app",
+    "dependsOn": [
+      "library"
+    ]
+  },
+  {
+    "repo": "voice-to-voice",
+    "project": "TOGa Voice",
+    "framework": "2.0",
+    "role": "app",
+    "dependsOn": [],
+    "language": "python"
+  },
+  {
+    "repo": "ai-bdr",
+    "project": "AI-BDR",
+    "framework": "2.0",
+    "role": "app",
+    "dependsOn": []
+  },
+  {
+    "repo": "forward",
+    "project": "Forwarder",
+    "framework": "standalone",
+    "role": "app",
+    "dependsOn": []
+  }
 ]

package/knowledge/standalone/apps/forward/INDEX.md

@@ -0,0 +1,6 @@
+# forward (Forwarder) — standalone knowledge
+
+| Doc | Summary | Files |
+|-----|---------|-------|
+| [Forwarder Architecture](architecture.md) | Forwarder is a tiny **standalone PHP application** that powers TOGA's short, branded redirect domains. | forward/forward.ini, forward/index.php, forward/.htaccess, forward/.platform/httpd/conf.d/rewritemap.conf, forward/.ebextensions/rewritemap.config, forward/composer.json |
+| [Encrypted-Link Handler](features/encrypted-link-handler.md) | A `index.php` feature in [Forwarder](../architecture.md) for redirect domains whose URL path carries an **encrypted token** that must be decoded before redirect | forward/index.php |

package/knowledge/standalone/apps/forward/architecture.md

@@ -0,0 +1,121 @@
+---
+title: Forwarder Architecture
+framework: "standalone"
+repo: forward
+project: Forwarder
+client: shared
+type: architecture
+status: active
+updated: 2026-06-18
+owners: [jcardinal]
+files:
+  - forward/forward.ini
+  - forward/index.php
+  - forward/.htaccess
+  - forward/.platform/httpd/conf.d/rewritemap.conf
+  - forward/.ebextensions/rewritemap.config
+  - forward/composer.json
+related: []
+---
+
+# Forwarder Architecture
+
+Forwarder is a tiny **standalone PHP application** that powers TOGA's short, branded
+redirect domains. The pattern: point a short **CNAME** (e.g. `powerbi.togatech.com`,
+`feedback.agilantsolutions.com`) at the Forwarder app running on **AWS Elastic Beanstalk**
+(Amazon Linux 2023 / Apache), and Forwarder issues an HTTP redirect to the real
+destination. It does **not** use either PHP framework (1.0 `App_` or 2.0 `_underscore`),
+which is why it lives under the `standalone/` knowledge partition.
+
+Local path on dev machines is tracked in Claude memory (`repo-path-forward`), not here.
+
+## Two layers: zero-compute map vs. light PHP compute
+
+Forwarder has two distinct redirect mechanisms. The vast majority of traffic never
+touches PHP at all.
+
+### 1. Zero-compute redirects (the common case) — Apache `RewriteMap` + `forward.ini`
+
+The `.htaccess` at the repo root drives a plain-text lookup table:
+
+- `forward.ini` is an Apache **`txt` RewriteMap** of `source destination` lines:
+  - `source` = full host or `host/path` (no scheme, no trailing slash)
+  - `destination` = full target URL (query strings allowed)
+  - Blank lines and `#` comments are ignored.
+- The `RewriteMap forwardmap txt:/var/www/html/forward.ini` directive **cannot** live in
+  `.htaccess` (must be server/VirtualHost scope), so it is deployed separately (see
+  Deployment below).
+- **Match precedence in `.htaccess`:**
+  1. Exact `HTTP_HOST + REQUEST_URI` match → `302` (flags `NE,QSA`).
+  2. Else `HTTP_HOST`-only match → `302`, appending the original path + query to the
+     destination.
+  3. Else, if the request is not a real file/dir, fall through to `index.php`.
+- **Operational win:** editing `forward.ini` takes effect **immediately** — Apache
+  re-reads the txt map on the next request after a graceful reload (`sudo systemctl
+  reload httpd`); no redeploy or restart needed. Most "add a redirect" requests are a
+  one-line edit to `forward.ini`.
+- **Authoring rule:** put the most **specific** `host/path` lines **before** the general
+  `host`-only line, or the general line matches first and the path line is never reached
+  (documented in the `forward.ini` header).
+- **Health check:** `.htaccess` short-circuits to `200 OK` for `ELB-HealthChecker`
+  user-agents and localhost / private-IP hosts (`127.*`, `10.*`, `172.*`, `192.168.*`),
+  so AWS ELB health checks pass without a map entry.
+
+### 2. Light compute (the exception) — `index.php`
+
+`index.php` is reached only when no map entry matched. It handles three cases:
+
+- **Encrypted-link handler** — for a hardcoded `$encryptedDomains` allowlist (PCMatic /
+  Newegg / `forward.*` agent-download domains), it extracts the encrypted path segment
+  (by a per-domain `offset`: `0` = first segment, `1` = second), runs `decrypt()`, then
+  `302`s to the domain's configured base URL with the decrypted value `urlencode`d
+  appended. Invalid/empty/tampered input returns a styled `400`. See the
+  [encrypted-link-handler](features/encrypted-link-handler.md) feature doc.
+- **Local directory handler** — if the first host label matches a directory in the repo
+  (e.g. `sos.*` → `/sos/`), it redirects to `/<subdomain>/` and serves that dir's
+  `index.html`. Used for the bundled `sos/` Splashtop SOS download page.
+- **404** — otherwise returns a styled `404` echoing the unmatched `host + uri`.
+
+## Deployment (Elastic Beanstalk / Apache)
+
+- Runs on **Elastic Beanstalk**, Amazon Linux 2023, Apache `httpd`.
+- The `RewriteMap` definition is deployed to `/etc/httpd/conf.d/rewritemap.conf` two ways
+  for cross-platform safety:
+  - `.platform/httpd/conf.d/rewritemap.conf` — the **Amazon Linux 2+/2023** mechanism
+    (current).
+  - `.ebextensions/rewritemap.config` — legacy **Amazon Linux 1** `files:` fallback.
+    Both can coexist; AL2+ ignores the `.ebextensions` file path managed by `.platform`,
+    and AL1 ignores `.platform` entirely.
+- `forward.ini` deploys to `/var/www/html/forward.ini` (the path the map points at).
+- `composer.json` declares a `Togatech\Forward\` PSR-4 autoload over `src/` but has **no
+  dependencies** and no `src/` is shipped today — the app is effectively a single
+  `index.php` plus the Apache config.
+
+## The `decrypt()` scheme
+
+`decrypt()` in `index.php` is a **home-rolled** symmetric scheme, used only to obfuscate
+agent-download tokens in URLs — **not** real encryption and not for protecting secrets:
+
+1. URL-safe base64 normalize (`-_` → `+/`); the **last char** is a stored integrity hash.
+2. base64-decode the remainder; the **first byte** is the key-start seed.
+3. Regenerate a keystream from the seed (`i += i` per step, `chr(i % 255)`) and XOR it
+   against the payload to recover the plaintext.
+4. Verify by recomputing the first char of `base64(hmac_sha256(payload, key))` and
+   comparing to the stored hash; mismatch → empty string (treated as failure → `400`).
+
+Treat this as obfuscation only. Anything genuinely sensitive must not rely on it.
+
+## Notes / gotchas
+
+- **No restart needed for new redirects** — edit `forward.ini`, reload httpd. This is the
+  single most useful operational fact about this app.
+- Specific-path map lines must precede host-only lines (see `forward.ini` header).
+- New **encrypted** domains require a code change (`$encryptedDomains` in `index.php`),
+  not just a `forward.ini` edit.
+- `index.php` only runs on a map miss, so a bad/over-broad `forward.ini` host-only line
+  can shadow paths you expected PHP to handle.
+
+## Change history
+
+- 2026-06-18 (jcardinal) — Initial architecture documentation; registered `forward`
+  (Forwarder, standalone) in the knowledge base.

package/knowledge/standalone/apps/forward/features/encrypted-link-handler.md

@@ -0,0 +1,70 @@
+---
+title: Encrypted-Link Handler
+framework: "standalone"
+repo: forward
+project: Forwarder
+client: shared
+type: feature
+status: active
+updated: 2026-06-18
+owners: [jcardinal]
+files:
+  - forward/index.php
+related:
+  - standalone/apps/forward/architecture.md
+---
+
+# Encrypted-Link Handler
+
+A `index.php` feature in [Forwarder](../architecture.md) for redirect domains whose URL
+path carries an **encrypted token** that must be decoded before redirecting — used for
+remote-support / agent-download links (PCMatic, Newegg, generic `forward.*` agent
+downloads) where the trailing value (e.g. a user identifier) is obfuscated in the path.
+
+## When it runs
+
+Only when the Apache `RewriteMap` (`forward.ini`) produced **no match** and the request
+falls through to `index.php`, and the lowercased `HTTP_HOST` is a key in the hardcoded
+`$encryptedDomains` allowlist near the top of `index.php`.
+
+## Configuration
+
+`$encryptedDomains` maps a host to `['url' => <base>, 'offset' => <int>]`:
+
+- `url` — the destination base URL; the decrypted value is `urlencode`d and appended.
+- `offset` — which **0-based path segment** holds the encrypted token:
+  - `0` → `host.com/ENCRYPTED`
+  - `1` → `host.com/prefix/ENCRYPTED`
+
+Adding a new encrypted domain is a **code change** (edit `$encryptedDomains`), not a
+`forward.ini` edit.
+
+## Flow
+
+1. Split the request path on `/`; take the segment at `offset` as the token.
+2. Empty token → styled **`400` Invalid Link**.
+3. `decrypt($token)` (see below); failure (empty return) → styled **`400` Decryption
+   Failed**.
+4. Success → `header('Location: ' . $base . urlencode($decrypted), 302)`.
+
+## The `decrypt()` algorithm
+
+Custom symmetric scheme — **obfuscation, not real encryption**:
+
+1. Restore URL-safe base64 (`-_` → `+/`). The **final character** is a stored 1-char
+   integrity hash; strip and keep it.
+2. base64-decode the rest. The **first byte** is the key-start seed; the remainder is the
+   payload.
+3. Regenerate a keystream from the seed — `for (i = seed, j = 0; j < len; i += i, j++)
+   key .= chr(i % 255)` — and XOR it byte-for-byte against the payload to recover the
+   plaintext.
+4. Integrity check: recompute `substr(base64_encode(hash_hmac('SHA256', payload, key,
+   true)), 0, 1)` and compare to the stored hash char. Mismatch → return `''` (→ `400`).
+
+Because it is home-rolled and uses only a single hash character for integrity, treat it
+strictly as link obfuscation. Do not use it to protect anything sensitive.
+
+## Change history
+
+- 2026-06-18 (jcardinal) — Initial documentation of the encrypted-link handler during
+  Forwarder onboarding into the knowledge base.

package/package.json

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