toga-ai 1.0.181 → 1.0.183

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

@@ -5,7 +5,7 @@
 | [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 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, test/@dave/probe_missing_oo_timing.php, test/@dave/probe_missing_oo_createdby.php, test/@dave/probe_drift_so_dates.php, worker/crons/toga2/forecast2/common_import_sales_from_netsuite.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, test/@dave/probe_missing_oo_timing.php, test/@dave/probe_missing_oo_createdby.php, test/@dave/probe_drift_so_dates.php, test/@dave/probe_profit_invoices.php, test/@dave/probe_profit_gap.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 |
 | [Onboarding a Client to the NetSuite TOGa Supply Sync](workflows/onboarding-client-to-netsuite-togasupply-sync.md) | How to add a new TOGa 2 client to the per-client NetSuite → TOGa Supply importer (`worker/crons/toga2/netsuite/`). | worker/crons/toga2/netsuite/sync_togasupply.php, worker/crons/toga2/netsuite/common_sync_togasupply.php, worker/schedules/cron.worker.sync.json, dbchanges2/_modules/netsuite/2026-04-01 - Parameters.sql |

package/knowledge/1.0/apps/worker/features/forecast2-netsuite-reconciliation.md

@@ -6,7 +6,7 @@ project: Worker
 client: shared
 type: feature
 status: active
-updated: 2026-06-23
+updated: 2026-06-24
 owners: [dfranks]
 files:
   - test/@dave/reconcile_netsuite_totals.php
@@ -18,6 +18,8 @@ files:
   - test/@dave/probe_missing_oo_timing.php
   - test/@dave/probe_missing_oo_createdby.php
   - test/@dave/probe_drift_so_dates.php
+  - test/@dave/probe_profit_invoices.php
+  - test/@dave/probe_profit_gap.php
   - worker/crons/toga2/forecast2/common_import_sales_from_netsuite.php
 related:
   - ../architecture.md
@@ -35,9 +37,14 @@ by reconciling a chosen tranDate range directly against NetSuite.
 
 ## Key files / entry points
 
-- `reconcile_netsuite_totals.php [from] [to]` — category grand totals NS vs Forecast2 (Sales,
-  Sales Profit, Open Orders, Opportunities) with deltas. Read-only. Connects explicitly to the
-  **prod core2 reader**; NetSuite via SuiteQL SUMs.
+- `reconcile_netsuite_totals.php [from] [to] [--verbose]` — category grand totals NS vs Forecast2
+  (Sales, Sales Profit, Open Orders, Opportunities) with deltas. Read-only. Connects explicitly to
+  the **prod core2 reader**; NetSuite via SuiteQL SUMs. `--verbose` additionally prints the
+  per-transaction presence diffs (Sales `salesPerTransactionDiff()` + Open Orders
+  `openOrderPerOrderDiff()`), each under a large `#`-banner heading with a date column in every
+  bucket. The diffs are **gated** because they materialize every transaction/order in the window
+  into PHP arrays and OOM on multi-year windows — default is summary-only; positional `[from] [to]`
+  work alongside the flag.
 - `analyze_netsuite_forecast_diff.php [from] [to]` — decomposes the delta **per transaction** into
   NS_ONLY (missing from FC), FC_ONLY (stale/extra), DRIFT (value differs). Read-only.
 - `trueup_sales.php --from --to [--chunk-days N] [--prod] [--dry-run]` — makes `Forecast.Sales`
@@ -49,6 +56,11 @@ by reconciling a chosen tranDate range directly against NetSuite.
   ~4,000 opps in ~13s to a $0 delta.
 - `probe_sales_gap_direct.php` / `probe_open_orders_gap.php` — read-only NS-vs-FC2 revenue
   breakdowns by type+month using **direct prod mysqli** (demonstrate the sandbox-dev bypass below).
+- `probe_profit_gap.php` — read-only: attributes a Sales **profit** delta **by transaction type**
+  and measures the actual contribution of the `tl.iscogs='F'` filter (see the COGS gotcha below).
+- `probe_profit_invoices.php` — read-only per-invoice profit localizer: lists drifted invoices
+  (`id` / `tranid` / `tranDate` / NS profit / FC profit / delta) over a tranDate window. Bootstraps
+  worker2's `_Component_Api_Netsuite` adapter + a direct prod core2 `Forecast` reader.
 
 ## How it works
 
@@ -88,6 +100,36 @@ None — Forecast2 is a single shared dataset.
 
 ## Gotchas / known issues
 
+- **An audit must apply the sync's own inclusion rules or it manufactures phantom deltas.**
+  `reconcile`'s NetSuite Sales SUM/diff originally had **no transaction-status filter**, but the
+  sync (`trueup_sales` / `common_import_sales_from_netsuite.php`) deliberately **excludes** Invoice
+  *Voided*/*Rejected*, CashSale *"Unapproved Payment"*, and CreditMemo *Voided*. So the audit counted
+  rows the sync would never store → a **permanent phantom gap no true-up could ever close** (a single
+  Unapproved-Payment cash sale, $23.76, internalId 7184894, drove it). Fix: add a status filter
+  matching the sync to **both** Sales SUM queries and the per-transaction diff —
+  `BUILTIN.DF(t.status) NOT LIKE '%Unapproved Payment' / '%Voided' / '%Rejected'` (the display value
+  ends with the status name). Closed the revenue delta to `$0`. Generalize: when an audit reports a
+  delta no trueup closes, first check the audit applies the sync's exact inclusion filters.
+- **Don't blame a profit delta on COGS lines without measuring it.** Adding `tl.iscogs='F'` to the
+  audit's profit SUM (to match the sync's line set) changed the profit number by **exactly $0.00** in
+  the tested window — COGS postings were **not** the cause of the profit gap. The filter is kept for
+  definitional consistency with the sync (which filters `iscogs='F'`), but it was not the fix.
+  `probe_profit_gap.php` measures the iscogs contribution directly so the next investigator doesn't
+  repeat the wrong hypothesis.
+- **A Sales PROFIT-only gap (revenue matches, profit off) is a LINE-STRUCTURE mismatch, not value
+  drift — localize then window.** Production `Forecast.Sales` carries stale lines NetSuite no longer
+  returns *plus* is missing some, so the per-invoice profit SUM differs while revenue ties out.
+  `trueup_sales` surfaces this as **inserted>0 + deleted>0 with updated=0** (it reconciles by
+  `(type, txnId, lineNumber)`; a changed lineNumber is delete+insert, not update). **Key:**
+  `trueup_sales` *does* correct profit, but **only within its `--from/--to` tranDate window** — the
+  delta persists if the drifted transactions fall outside the window trued up. Diagnostic ladder:
+  (a) `reconcile` summary shows a profit delta with revenue at `$0`; (b) `probe_profit_gap.php`
+  attributes the delta to a transaction **type** (was 100% invoices); (c) `probe_profit_invoices.php`
+  lists the specific drifted invoices with tranDate; (d) run `trueup_sales --from/--to` over **that
+  exact window** with `--prod`. Resolved example: 23 invoices dated 2026-05-07/08 carried $1,277.37;
+  `trueup_sales --prod` over 2026-05-07..2026-05-08 applied 12 inserts + 35 deletes → `$0`. ⚠
+  `--prod` must be passed or trueup writes to the **laptop sandbox `db_forecast2`** (and that repoint
+  also drives which `Forecast.Items` lookup loads).
 - **NVL the cost in NS profit SUMs.** `reconcile`/`analyze` compute NS profit as
   `SUM(-foreignamount + NVL(costestimate,0))`. Without `NVL`, ShipItem lines (NULL cost) drop from
   the SUM and NS profit is understated, producing a **fake FC-over-NS "gap"** ($663K across 2025).
@@ -169,6 +211,13 @@ None — Forecast2 is a single shared dataset.
 
 ## Change history
 
+- 2026-06-24 — **Sales audit correctness pass.** Fixed a phantom Sales delta: `reconcile`'s NS Sales
+  SUM/diff now applies the sync's status exclusions (Unapproved Payment / Voided / Rejected) so it can't
+  count rows the sync never stores (closed revenue delta to $0). Added a Sales per-transaction presence
+  diff and gated both diffs behind `--verbose` (they OOM on wide windows). Documented that a profit-only
+  gap is a line-structure mismatch fixed by `trueup_sales` **only within its tranDate window**
+  (localize-then-window ladder), and that `tl.iscogs='F'` contributed exactly $0.00 — COGS was not the
+  cause. Added `probe_profit_invoices.php` + `probe_profit_gap.php`. (dfranks)
 - 2026-06-23 — **Framed open-orders drift as three distinct categories** mapping to
   `trueup_open_orders`'s Insert/Update/Delete buckets — whole-order-missing (dominant by $),
   line-level value drift (largest by count), and stale FC rows (smallest) — correcting the common

package/knowledge/standalone/apps/forward/features/design-demo-admin.md

@@ -6,7 +6,7 @@ project: Forwarder
 client: shared
 type: feature
 status: active
-updated: 2026-06-23
+updated: 2026-06-24
 owners: ["jcardinal"]
 files:
   - forward/design/index.php
@@ -83,9 +83,21 @@ auto-deploy ("live in a few minutes").
   regenerates the stub.
 - **Remove = unlist only** — sets a `hidden` flag in `project.json`; files are **never
   deleted** (explicit owner decision).
+- **Edit version metadata** (`apiEditVersion`) — an "Edit" button on each version row opens
+  a modal pre-filled with the version's label, author ("your name"), and notes. Saving
+  commits an **updated `project.json` only** — the version id and the hosted `vN/index.html`
+  are unchanged, and the redirect stub does not depend on this metadata, so **no stub
+  rebuild**. Reuses the existing `isValidVersionId` guard and `postField` length caps (notes
+  cap 2000).
+- **Copy URL** — a button on each project card copies the project's main live URL
+  (`https://demo.togatech.com/<project>`) to the clipboard via `navigator.clipboard`, with a
+  brief "Copied ✓" confirmation.
 - **Copy Claude Design prompt** — one-click copy of the standard self-contained-HTML export
   prompt (the same prompt documented in [static-demo-hosting](static-demo-hosting.md)).
 
+The full action set is: `list`, `create-project`, `upload`, `adopt`, `set-latest`,
+`toggle-version`, `edit-version`, `toggle-project` (plus `bootstrap`).
+
 ### Naming & validation
 
 - Folder names auto-normalized to **lowercase kebab-case**, validated against a kebab regex
@@ -141,6 +153,11 @@ None — internal/shared design-team tool.
   `/vN` versioning with a `project.json` manifest + auto-generated latest-pointer stub,
   adopt/unlist actions, `/design` route. Fixed the >1 MB Contents-API empty-content bug
   (raw media type) and the tracked-token leak (env/`.config.php`). (jcardinal)
+- 2026-06-24 — Added **edit-version** (`apiEditVersion`): an Edit button + modal to revise a
+  version's label/author/notes, committing `project.json` only (no stub rebuild; reuses
+  `isValidVersionId` + length caps). Added a **Copy URL** button on each project card
+  (`navigator.clipboard` → `https://demo.togatech.com/<project>`). Both additive; no new
+  security surface. (jcardinal)
 
 ## Related docs
 

package/package.json

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