toga-ai 1.0.124 → 1.0.126

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

@@ -4,4 +4,4 @@
 |-----|---------|-------|
 | [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 |
-| [AWS Amplify Build & Deploy (non-prod environments)](workflows/amplify-build-and-deploy.md) | How `toga2-supply` (React + Vite) builds and deploys to **AWS Amplify** for non-prod environments (Stage, QC Security, QC Performance, …). | toga2-supply/amplify.yml, toga2-supply/.github/workflows/sync-stage-environments.yml, toga2-supply/.env.qc-security |
+| [AWS Amplify Build & Deploy (non-prod environments)](workflows/amplify-build-and-deploy.md) | How `toga2-supply` (React + Vite) builds and deploys on **AWS Amplify**. | toga2-supply/amplify.yml, toga2-supply/.github/workflows/sync-stage-environments.yml, toga2-supply/.env.qc-security |

package/knowledge/2.0/apps/toga2-supply/workflows/amplify-build-and-deploy.md

@@ -6,7 +6,7 @@ project: TOGa Supply
 client: shared
 type: workflow
 status: active
-updated: 2026-06-17
+updated: 2026-06-18
 owners: ["jcardinal"]
 files:
   - toga2-supply/amplify.yml
@@ -18,87 +18,90 @@ related:
 
 ## Summary
 
-How `toga2-supply` (React + Vite) builds and deploys to **AWS Amplify** for non-prod
-environments (Stage, QC Security, QC Performance, …). The **alpha/beta/gamma/production**
-environments historically deploy via **GitHub Actions** (`.github/workflows/*.yml`) into the
-`agilantsolutions/toga2-supply-build` repo — Amplify is the path used for the newer non-prod
-environments. The first Amplify build failed with a JavaScript heap OOM; this doc records the
-fix and the chosen **branch-per-environment** deployment model.
-
-## Deployment model — branch per environment, mirrored from `_stage`
-
-The unit of an environment in Amplify is a **branch** (idiomatic Amplify: branch = environment).
-A single branch cannot fan out to multiple environments, and a branch can only be connected once
-per Amplify app. So:
-
-- **`_stage` is the integration branch** — where work lands and is reviewed. It is **not deployed
-  directly**.
-- Each environment is its **own deployment branch** that mirrors `_stage` exactly:
-  `stage`, `qc-security`, `qc-performance`, …
-- **Branch name == Vite mode == `.env.<branch>` filename.** `amplify.yml` builds with
-  `--mode "$AWS_BRANCH"` (Amplify injects `$AWS_BRANCH`), so branch `qc-security` builds
-  `--mode qc-security` and loads `.env.qc-security`. No per-branch env var needed.
-- A GitHub Action (`sync-stage-environments.yml`) **fast-forwards every environment branch to
-  `_stage` on each push**, triggering each branch's Amplify build with its own mode.
+How `toga2-supply` (React + Vite) builds and deploys on **AWS Amplify**. Each Amplify
+**branch is one environment** (`_production`, `_beta`, `_gamma`, `_stage`, `_qc-security`,
+`_qc-performance`, …). The first Amplify build failed with a JavaScript heap OOM, and a later
+attempt **broke production** by silently pointing it at beta — this doc records both the heap
+fix and the branch→mode mapping that prevents the mis-pointing.
+
+## Deployment model — one branch per environment
+
+- Branch names are **underscore-prefixed** (`_production`, `_qc-security`); the Vite **mode**
+  and `.env` file are the **same name WITHOUT the underscore** (`production`, `qc-security`).
+- The repo-root **`amplify.yml` drives the build for every branch** (it overrides the Amplify
+  console build spec for the whole app — including `_production`). It:
+  - Sets `NODE_OPTIONS=--max-old-space-size=8192` (the OOM fix; matches production), runs
+    `npm ci --legacy-peer-deps`, caches `.npm`.
+  - Derives the mode by **stripping the leading underscore** from `$AWS_BRANCH`
+    (`MODE="${AWS_BRANCH#_}"`), then runs `npx tsc && npx vite build --mode "$MODE"`.
+  - **Fails the build loudly** (`exit 1`) if `.env.$MODE` does not exist — see the gotcha below.
+- `_stage` is **both** the Stage environment (builds `--mode stage`) **and** the integration
+  source for the QC environments. The `sync-stage-environments.yml` GitHub Action fans `_stage`
+  out to `_qc-security` and `_qc-performance` on every push (fast-forward `--force-with-lease`),
+  triggering each QC branch's own Amplify build.
 
 ```
-_stage (integration, not deployed)
-   │  push → sync-stage-environments.yml fast-forwards ↓
-   ├──▶ stage           ──▶ Amplify ──▶ build --mode stage
-   ├──▶ qc-security     ──▶ Amplify ──▶ build --mode qc-security
-   └──▶ qc-performance  ──▶ Amplify ──▶ build --mode qc-performance
+_production ──▶ Amplify ──▶ build --mode production  (.env.production)
+_beta       ──▶ Amplify ──▶ build --mode beta
+_gamma      ──▶ Amplify ──▶ build --mode gamma
+_stage ──▶ Amplify ──▶ build --mode stage
+   │ push → sync-stage-environments.yml fast-forwards ↓
+   ├──▶ _qc-security    ──▶ Amplify ──▶ build --mode qc-security
+   └──▶ _qc-performance ──▶ Amplify ──▶ build --mode qc-performance
 ```
 
 ## Steps
 
-1. **`amplify.yml` (repo root) drives the build.** When present it **overrides the Amplify
-   console build settings entirely** — you cannot split "memory in the file, build command in the
-   console." It sets `NODE_OPTIONS=--max-old-space-size=4096` (the OOM fix) and runs
-   `npx tsc && npx vite build --mode "$AWS_BRANCH"`, publishing `dist/`.
-2. **In the Amplify app, connect one branch per environment** (`stage`, `qc-security`,
-   `qc-performance`, …). Each branch is its own environment with its own hosting domain.
-3. **Each environment needs a committed `.env.<branch>` file** (Vite loads `.env.<mode>`).
-   e.g. `.env.qc-security` provides `VITE_API`.
-4. **Add the branch to the sync matrix.** Edit `sync-stage-environments.yml` → `matrix.branch`.
-5. Push to `_stage`; the Action mirrors the env branches; Amplify rebuilds each.
+1. **Connect one Amplify branch per environment** (underscore-prefixed). Within a single
+   Amplify app a branch connects only once — you cannot point multiple environments at the same
+   branch connection, which is why each environment is its own branch.
+2. **Commit a matching `.env.<mode>` file** (no underscore): `.env.production`, `.env.beta`,
+   `.env.gamma`, `.env.alpha`, `.env.stage`, `.env.qc-security`. A new environment needs its
+   file before it can deploy (otherwise the build fails loudly by design).
+3. **For a fanned-out QC environment, add its underscore branch to the sync matrix** in
+   `sync-stage-environments.yml`.
+4. Push; Amplify builds each branch with its own mode. **Roll out `amplify.yml` changes on a
+   non-prod branch first** (it overrides production's build spec too).
 
 ## Systems involved
 
-- AWS Amplify (build + hosting) — one branch per environment, branch name selects the mode.
-- GitHub Actions — `sync-stage-environments.yml` mirrors `_stage` → env branches on push.
-- Vite 4 build (`vite build --mode <branch>`), TypeScript `tsc` precompile.
-- Sentry source-map upload via `@sentry/vite-plugin` (source maps are **on** —
-  `build.sourcemap: true` in `vite.config.ts`).
+- AWS Amplify (build + hosting) — one branch per environment; branch name (minus `_`) selects
+  the Vite mode and `.env` file.
+- GitHub Actions — `sync-stage-environments.yml` mirrors `_stage` → `_qc-security`,
+  `_qc-performance`. (Separately, `alpha/beta/gamma/production.yml` are the older GitHub-Actions
+  build path into `agilantsolutions/toga2-supply-build`.)
+- Vite 4 (`vite build --mode <mode>`), TypeScript `tsc` precompile. Source maps are **on**
+  (`build.sourcemap: true` in `vite.config.ts`).
 
 ## Edge cases & escalation
 
-- **OOM root cause:** Amplify gives Node the default ~2 GB old-space heap. This app
-  (1793 modules + source maps on) exceeds it during Rollup's `rendering chunks` phase →
-  `FATAL ERROR: Ineffective mark-compacts near heap limit`. Fix = raise `NODE_OPTIONS`.
-- **Heap vs. instance RAM:** `--max-old-space-size=4096` only helps if the build container
-  has ≥4 GB. Amplify **Standard** compute is 4 GB (tight with source maps on). If it OOMs
-  again, switch to the **Large build instance** (Amplify → App settings → Build settings)
-  and raise to `6144`/`7168`. Setting the heap above physical RAM makes it worse, not better.
-- **"Can't pick `_stage` again" in the UI:** within one Amplify app a branch connects only once.
-  This is why environments are separate *branches*, not multiple connections to `_stage`. (An
-  alternative — multiple Amplify *apps* all pointed at `_stage` — works but is a non-idiomatic
-  workaround: N apps to manage, no single dashboard. Branch-per-env is preferred.)
-- **Env branches are disposable deployment pointers — never commit to them directly.** The sync
-  Action force-updates them (`--force-with-lease`) to match `_stage`; any direct commit is lost.
-- **Branch name must match the mode/`.env` filename.** `--mode qc-security` loads
-  `.env.qc-security` exactly — a mismatch (e.g. a stray `.env.qc-security.beta`) is silently
-  ignored: the build succeeds but ships with no `VITE_API`.
+- **Silent wrong-endpoint trap (caused a production outage):** When Vite is given a `--mode`
+  with no matching `.env.<mode>`, it **silently falls back to the base `.env`** (which points at
+  beta) instead of erroring. An `amplify.yml` that built `--mode "$AWS_BRANCH"` therefore ran
+  `--mode _production` (no `.env._production`) and shipped beta endpoints to production. **Fix:**
+  strip the underscore to get the real mode, AND guard with `[ -f ".env.$MODE" ] || exit 1` so a
+  missing env file fails the build instead of mis-pointing.
+- **`amplify.yml` overrides production.** A repo-root `amplify.yml` replaces the console build
+  spec for **all** branches including `_production`. Validate any change on a non-prod branch
+  before it can reach production.
+- **OOM root cause:** Amplify gives Node the default ~2 GB old-space heap; this app
+  (1793 modules + source maps) exceeds it during Rollup's `rendering chunks` phase →
+  `FATAL ERROR: Ineffective mark-compacts near heap limit`. Fix = raise `NODE_OPTIONS`
+  (`8192` in production). Raising it only helps if the build instance has that much RAM; if it
+  still OOMs, use the **Large build instance**.
+- **Env branches are disposable deployment pointers** — the sync Action force-updates
+  `_qc-security`/`_qc-performance` to match `_stage`. Never commit to them directly.
 - **Secret hygiene:** `.env.<mode>` files have historically carried a live `SENTRY_AUTH_TOKEN`.
   Prefer rotating it and moving it to an Amplify env var rather than committing it.
 
 ## Change history
 
-- 2026-06-17 — Switched to branch-per-environment: `amplify.yml` now builds `--mode "$AWS_BRANCH"`
-  and added `sync-stage-environments.yml` to mirror `_stage` → env branches. (Superseded the
-  earlier `VITE_BUILD_MODE` per-branch-env-var idea — unworkable because multiple environments
-  must deploy from the single `_stage` branch.) (jcardinal)
-- 2026-06-17 — Created on first Amplify setup of a new QC environment: added root `amplify.yml`
-  with raised Node heap (OOM fix); renamed `.env.qc-security.beta` → `.env.qc-security`. (jcardinal)
+- 2026-06-18 — Fixed production-breaking deploy: `amplify.yml` now strips the leading `_` from
+  `$AWS_BRANCH` to get the Vite mode and **fails loudly** if `.env.$MODE` is missing (was
+  silently falling back to beta); heap set to 8192; sync workflow targets underscore-prefixed
+  `_qc-security`/`_qc-performance`. (jcardinal)
+- 2026-06-17 — Initial Amplify setup for a new QC environment: added root `amplify.yml` with
+  raised Node heap (OOM fix); renamed `.env.qc-security.beta` → `.env.qc-security`. (jcardinal)
 
 ## Related docs
 

package/knowledge/INDEX.md

@@ -30,7 +30,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)
+- **forward** (Forwarder) — 3 doc(s) → [standalone/apps/forward/INDEX.md](standalone/apps/forward/INDEX.md)
 
 ## Clients
 

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

@@ -4,3 +4,4 @@
 |-----|---------|-------|
 | [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 |
+| [Static Demo Hosting](features/static-demo-hosting.md) | A lightweight way to host self-contained static HTML pages (demos, exported designs, download landing pages) on the Forwarder app under a clean URL — e.g. | forward/.htaccess, forward/togadesk/index.html |

package/knowledge/standalone/apps/forward/features/static-demo-hosting.md

@@ -0,0 +1,115 @@
+---
+title: Static Demo Hosting
+framework: "standalone"
+repo: forward
+project: Forwarder
+client: shared
+type: feature
+status: active
+updated: 2026-06-18
+owners: ["jcardinal"]
+files:
+  - forward/.htaccess
+  - forward/togadesk/index.html
+related:
+  - standalone/apps/forward/architecture.md
+---
+
+## Summary
+
+A lightweight way to host self-contained static HTML pages (demos, exported designs,
+download landing pages) on the Forwarder app under a clean URL — e.g.
+`https://demo.togatech.com/togadesk`. The hostname stays in the browser and the page is
+served straight off disk with no redirect and no PHP compute. This is how we publish
+exported **Claude Design** mockups for stakeholders to view without the Claude editor /
+chat sidebar. First real use: the TOGa Desk design demo at `togadesk/`.
+
+## Key files / entry points
+
+- `forward/.htaccess` — a guarded static-serving rule placed **before** the `forward.ini`
+  RewriteMap rules.
+- `forward/<name>/index.html` — one directory per demo at the repo root (e.g.
+  `forward/togadesk/index.html`). Apache serves it directly.
+- A `demo.togatech.com` CNAME pointed at the Forwarder Elastic Beanstalk environment.
+
+## How it works
+
+The rule in `.htaccess`:
+
+```apache
+# Static demo hosting (e.g. demo.togatech.com/togadesk)
+RewriteCond %{DOCUMENT_ROOT}/$1/index.html -f
+RewriteRule ^([^/]+)/?$ /$1/index.html [L]
+```
+
+- Matches a single path segment (`/togadesk` or `/togadesk/`) and internally serves
+  `<docroot>/<segment>/index.html` — **no external redirect**, so the URL the user typed
+  stays in the address bar.
+- The `RewriteCond … -f` guard means the rule only fires when that `index.html` actually
+  exists, so it never interferes with the existing `forward.ini` redirect map; unmatched
+  paths fall through to the map and then `index.php` exactly as before.
+- It sits before the RewriteMap block on purpose, so a real demo file always wins over a
+  map lookup.
+
+**Adding a new demo** is therefore drop-in: create `forward/<name>/index.html`, commit,
+deploy the EB app → `demo.togatech.com/<name>` works immediately. No code or `.htaccess`
+change is needed for each new demo.
+
+This is distinct from the older subdomain-based **local directory handler** in `index.php`
+(`sos.*` → `/sos/`), which runs only on a map miss and issues a redirect. The static-demo
+rule is path-based, redirect-free, and runs in Apache before PHP. See the
+[architecture](../architecture.md) doc.
+
+## Exporting a Claude Design page for hosting
+
+Demos are typically Claude Design artifacts exported as a **single self-contained HTML
+file**. A generic prompt to give inside the Claude Design conversation (no design-specific
+names) that yields a downloadable file:
+
+> Package this design as a single, fully self-contained HTML file I can host anywhere, and
+> give it to me as a downloadable file (not a copy/paste code block). Requirements: one
+> file with no build step or local assets; inline all CSS and JS; embed images/fonts as
+> `data:` URIs or absolute `https://` URLs (no root-relative `/...` or relative `./...`
+> paths, and no `<base>` tag); remove anything tied to the editing environment (no
+> sidebar/chat refs, no live data calls back to the session — replace dynamic data with
+> static placeholder content); it must render when opened directly in a browser; set a
+> sensible `<title>` and viewport meta. Then save it as a downloadable `.html` file and
+> give me the download link.
+
+Before hosting, verify the export has: no `<base>` tag, no root-relative/relative asset
+paths, no `fetch`/XHR/API calls back to a live backend (a detached demo must be static),
+and that it renders when opened directly by double-clicking. Public `https://` CDN
+dependencies (Font Awesome, Lucide, Tailwind CDN, Google Fonts) are fine — but the page
+then needs internet to render fully.
+
+## Data model
+
+None — pure static file serving.
+
+## Client variations
+
+None — uniform, shared/internal.
+
+## Gotchas / known issues
+
+- **Bare domain root 404s.** `demo.togatech.com/` (no demo name) has no `forward.ini`
+  entry, so it falls through to `index.php` → 404. Add a `forward.ini` line if the root
+  should redirect somewhere.
+- **The rule matches any host, not just `demo.togatech.com`.** It is guarded by the file
+  existence check, so `anyhost/togadesk` would also serve the demo. Acceptable today since
+  only the `demo` CNAME is meant to be used; keep demo directory names from colliding with
+  real first-path-segment redirect targets.
+- **CDN dependencies need internet.** Exported pages that link CDN CSS/JS won't render
+  fully offline. Fine for hosted demos.
+- **Large files are fine but bloat the repo.** Exports with base64-inlined assets can be
+  multi-MB (the TOGa Desk demo is ~4 MB). They deploy with the EB app like any other file.
+
+## Change history
+
+- 2026-06-18 — Added static demo hosting: `.htaccess` rule + `togadesk/` demo; documented
+  the Claude Design export prompt (jcardinal).
+
+## Related docs
+
+- [Forwarder Architecture](../architecture.md)
+- [Encrypted-Link Handler](encrypted-link-handler.md)

package/package.json

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