toga-ai 1.0.1144 → 1.0.1145

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

@@ -5,7 +5,7 @@ project: Library
 client: shared
 type: standard
 status: active
-updated: 2026-10-23
+updated: 2026-10-24
 owners: [jcardinal, rgirish, mhammontree, ajean, bala]
 files: []
 related:
@@ -569,6 +569,16 @@ Never persist a generated file on local disk to hand to a *second* request. Our
 several instances behind a shared load balancer, so per-instance paths like `/var/www/cache`
 are not shared and the follow-up request intermittently 404s. One request, start to finish.
 
+## Time zones — store Central, convert for display
+
+**Hard rule (team-wide):** every date and time stored in the database must be pre-converted to Central time (`America/Chicago`). See [org/standards/time-zones.md](../../org/standards/time-zones.md).
+
+1.0 specifics (verified in `library`):
+- `library/_.php` calls `date_default_timezone_set('America/Chicago')`, so `date()`, `time()`-based values and `App_Date::getTimeNow()` are naive Central. Do not change the default zone in app code.
+- Convert with `App_Date::convertToTimezone($datetime, $format, $phpTimezone)` (outputs in the target zone, restores the default) or `App_Date::convertTimezone()` / `convertTimezoneToEpoch($datetime, $inputTimezone)`. Convert inbound UTC feeds to Central before saving; convert only for display or an outbound payload.
+- `App_Date::getTimeNow(true)` adds the local user offset for display; never save that value.
+- 1.0 has no viewer-zone setting layer; display zone logic is app-specific.
+
 ## Documentation
 
 - Keep code well-documented with DocBlocks and usage examples.

package/knowledge/1.0/standards/frontend.md

@@ -5,7 +5,7 @@ project: Library
 client: shared
 type: standard
 status: active
-updated: 2026-09-16
+updated: 2026-10-24
 owners: [jcardinal]
 files: []
 related:
@@ -74,3 +74,7 @@ When retrofitting light/dark onto a legacy sheet, four rules turn a guessing gam
 Two things are **never** tokenised: HTML destined for an **email** (email clients cannot resolve custom properties) and colours deliberately matched to third-party embedded content (e.g. an iframe's canvas colour, to prevent a white flash on load).
 
 Reference implementation (tools App-Wide Colour Theme) — see frontend-cases.md.
+
+## Time zones
+
+Hard rule (team-wide): dates and times are stored in Central (`America/Chicago`). Convert user input to Central before sending; convert from Central only to display. Never treat a server datetime as browser-local or UTC. See [org/standards/time-zones.md](../../org/standards/time-zones.md) and [backend-php.md § Time zones](backend-php.md#time-zones--store-central-convert-for-display).

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

@@ -1030,10 +1030,9 @@ See: 2.0/apps/worker2/features/cross-account-aws-access.md (role model),
 
 ## Time zones — store Chicago, convert for the user
 
-- **Hard rule:** every date and time stored in the database must be pre-converted to Central time (`America/Chicago`) before it is saved. The caller (front end, worker, import) converts from the user's zone to Central before sending; the stored value is never in any other zone. Convert back to the viewer's zone only for display.
-- Technician working hours and time off (Desk Dispatch, TRUE-82916) follow it too: stored as Central clock times.
-- The api2 `Config/*.ini` files set `timezone = "America/Chicago"`, so PHP and SQL datetimes are naive Chicago. Never store UTC or a user's local time.
-- The user's zone is a **setting** (slug `time-zone`, settings layer): global default `America/Chicago` (`Core.DefaultGlobalSettings`), a client can override, a user can override. Only the **display** converts; storage never does.
+- **Hard rule (team-wide, all frameworks):** [org/standards/time-zones.md](../../org/standards/time-zones.md). Store Central (`America/Chicago`); convert only for display.
+- 2.0 specifics: the api2 `Config/*.ini` files set `timezone = "America/Chicago"`, so PHP and SQL datetimes are naive Chicago. Desk Dispatch (TRUE-82916) working hours and time off are Central clock times.
+- The viewer zone is a **setting** (slug `time-zone`, settings layer): global default `America/Chicago` (`Core.DefaultGlobalSettings`), client and user can override.
 - Resolve with `_Component_SlaCalendar::resolveTimeZone()` (user setting, else client setting, else Core default, else PHP default). `assertStorageZone()` throws if the DB clock and PHP default zone differ — keep them equal.
 - The viewer's zone travels the same path as language and currency: api2 resolves the `time-zone` setting through the settings cascade at token mint (user, else client, else global Chicago), embeds it in the token, and returns `audience.timeZone` on every answer and refresh. blox keeps it in a session store (`useSessionTimeZone`, like `useSessionCurrency`). Apps read the viewer's zone only from there, never from settings rows.
 - Planned (not built yet): the preferred date format and time format settings will travel the same path (token + audience + blox session store).

package/knowledge/2.0/standards/frontend.md

@@ -775,7 +775,7 @@ Copy from there rather than reinventing.
 
 ## 25. Time zones — convert from the storage zone — **MUST**
 
-- **Hard rule:** every date and time stored in the database must be pre-converted to Central time (`America/Chicago`) before it is saved. The front end converts from the user's zone to Central before sending; convert back to the viewer's zone only for display. Technician working hours and time off (Desk Dispatch, TRUE-82916) are stored as Central clock times.
+- **Hard rule (team-wide, all frameworks):** [org/standards/time-zones.md](../../org/standards/time-zones.md). The front end converts the user's zone to Central before sending; convert back only for display. Desk Dispatch (TRUE-82916) working hours and time off are Central clock times.
 - The server stores and returns datetimes in **Chicago time** (`America/Chicago`), with no zone marker. **Never treat a server datetime as browser-local or UTC** (`new Date("2026-10-24 09:00:00")` is wrong).
 - Convert **explicitly from `America/Chicago`** to the user's zone, using one shared helper (desk: `src/utils/serverTime.ts`). Send datetimes back in Chicago time.
 - The user's zone is a setting (`time-zone`: user, else client, else global Chicago default). api2 resolves it at token mint and returns `audience.timeZone` on every answer and refresh; blox keeps it in a session store (`useSessionTimeZone`, like `useSessionCurrency`). Read the viewer's zone only from there; never read settings rows yourself and never hard-code it.

package/knowledge/org/knowledge-map.md

@@ -24,6 +24,7 @@ Where each kind of knowledge lives. The prompt's taxonomy (product, architecture
 | infrastructure | `devops` agent + AWS docs (fetched live); deploy notes in workflow docs |
 | security | `rules/toga/common/security.md` + `cso` |
 | decisions | `knowledge/org/decisions/` (ADRs) |
+| team-wide standards (all frameworks) | `knowledge/org/standards/` (e.g. `time-zones.md`: store Central) |
 | troubleshooting | gotchas attached to the owning team-KB feature/workflow doc + prod Logs |
 
 ## Why not build all ten folders now

package/knowledge/org/standards/time-zones.md

@@ -0,0 +1,24 @@
+# Time zones — team-wide hard rule (all frameworks, all repos)
+
+Applies to 1.0, 2.0, and standalone apps. Single source; framework docs link here and add only their own details.
+
+## Rule
+
+**Every date and time stored in a database must be pre-converted to Central time (`America/Chicago`) before it is saved.**
+
+- The caller (front end, worker, import, API client) converts from the source zone to Central before the write. The stored value is never UTC and never a user's local time.
+- Stored values carry no zone marker. Read them as Central, never as browser-local or UTC.
+- Convert from Central to the viewer's zone **only for display**. Storage never converts.
+- Inbound external timestamps (UTC feeds such as NetSuite REST `lastModifiedDate`) convert to Central on the way in. Outbound feeds convert back out explicitly.
+- Working hours, time off, schedules: stored as Central clock times.
+
+## Viewer zone is a setting
+
+- Global default `America/Chicago`; a client can override; a user can override (user, else client, else global).
+- Only the display layer reads it. How each framework delivers it is framework-specific (see below).
+
+## Framework details
+
+- 2.0: [backend-php.md § Time zones](../../2.0/standards/backend-php.md#time-zones--store-chicago-convert-for-the-user) and [frontend.md § 25](../../2.0/standards/frontend.md#25-time-zones--convert-from-the-storage-zone--must) (`audience.timeZone`, blox `useSessionTimeZone`).
+- 1.0: [backend-php.md § Time zones](../../1.0/standards/backend-php.md#time-zones--store-central-convert-for-display) and [frontend.md](../../1.0/standards/frontend.md).
+- Standalone apps: same rule; no framework helper, so convert explicitly.

package/package.json

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