toga-ai 1.0.436 → 1.0.438

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

@@ -3,6 +3,7 @@
 | Doc | Summary | Files |
 |-----|---------|-------|
 | [Tools (1.0 Internal-Tools App) Architecture](architecture.md) | **Tools** is a standalone 1.0 (`App_`) application that houses many small internal tools behind simple interfaces, gated by Client_True staff persona. | tools/index.php, tools/_/app/framework.php, tools/_/app/frameworkindex.php, tools/assets/img/favicon/favicon.ico, tools/assets/img/favicon/favicon-32x32.png, tools/assets/img/favicon/favicon-16x16.png, tools/assets/img/favicon/apple-touch-icon.png, tools/_/app/auth.php, tools/_/app/nav.php, tools/common/header.php, tools/common/footer.php, tools/mvc/get.php, tools/mvc/_TEMPLATE/get.php, tools/docs/ADDING_A_TOOL.md |
+| [CloudFront Client Setup](features/cloudfront-client-setup.md) | An SSO-gated admin tool at **`/devops/cloudfront-clients`** in the Tools 1.0 app that onboards a client onto **CloudFront + Route 53 across multiple AWS account | tools/_/app/devops/cloudfront.php, tools/mvc/devops/cloudfront-clients/get.php, tools/mvc/devops/cloudfront-clients/post.php, tools/assets/js/cloudfront-clients.js, tools/assets/css/cloudfront-clients.css, tools/_/app/nav.php, tools/_/app/frameworkindex.php, tools/config.production.ini |
 | [Design Demo Admin](features/design-demo-admin.md) | A self-serve admin UI at **`/design`** in the SSO-protected **Tools** app that lets the design team publish self-contained "Claude Design" HTML exports as **ver | tools/_/app/design/github.php, tools/mvc/design/get.php, tools/mvc/design/post.php, tools/assets/css/design.css, tools/assets/js/design.js, tools/_/app/frameworkindex.php, tools/_/app/nav.php, tools/composer.json |
 | [Tools — Developers Folder (UUID & Password Generators)](features/developer-tools.md) | The first two tools shipped in the Tools app, both under the **Developers** folder and gated to personas **Development Team** / **TOGa Technology**. | tools/mvc/developers/uuid/get.php, tools/mvc/developers/password/get.php |
 | [Tools MVC — Routing, CSRF & App_Database Access Patterns](features/mvc-data-access-patterns.md) | The load-bearing 1.0 (`App_`) framework conventions a developer needs when adding a page to the Tools app — URL routing, CSRF, and DB access through `App_Databa | tools/_/app/nav.php, tools/mvc/get.php |

package/knowledge/1.0/apps/tools/architecture.md

@@ -6,7 +6,7 @@ project: Tools
 client: shared
 type: architecture
 status: active
-updated: 2026-06-26
+updated: 2026-07-24
 owners: [jcardinal]
 files:
   - tools/index.php
@@ -44,8 +44,10 @@ dashboard stylesheet's `header{position:fixed;width:100vw}` rule and cause horiz
 (the top header bar was removed for exactly this reason). A nav action's `route` maps **1:1** to
 `mvc/<route>/get.php`. Auth fails **closed** and never auto-creates users; the dev bypass is
 double-gated (`[internal] dev_mode` AND `App_Registry::inDevMode()`). `config.*.ini`
-(incl. `config.prod.ini`) is committed with plaintext production secrets — a known, team-accepted
-risk (see Known issues); never add more secrets and treat these as compromised if leaked.
+(incl. `config.prod.ini`) is committed with plaintext production secrets that were **publicly
+web-readable** until the front-controller deny blocks added 2026-07-24 (see Known issues);
+rotation of every exposed secret is still owed. Never add more secrets, and keep config files
+denied at the front controller / out of the web root.
 
 ## Boot & structure
 
@@ -86,10 +88,15 @@ Create `mvc/<folder>/<tool>/get.php` (copy `mvc/_TEMPLATE/get.php`), add one ent
 
 ## Known issues / security
 
-- **Plaintext secrets committed to git.** `config.*.ini` (incl. `config.prod.ini`) contains
-  plaintext production secrets (RDS master password, SMTP, Payeezy, NetSuite). The team has
-  **accepted this for now** (developer decision, 2026-06-25). Future remediation: git-ignore the
-  config files and rotate all exposed credentials. (Location only — no values recorded here.)
+- **Plaintext secrets were publicly web-readable (fixed 2026-07-24; rotation still owed).**
+  `config.*.ini` (incl. `config.prod.ini`) holds plaintext production secrets (RDS master
+  password, SMTP, Payeezy, NetSuite). The front controller routed through `index.php` on a
+  `RewriteCond !-f` rule **only**, which is not access control — a direct
+  `GET /config.production.ini` served the file **verbatim**. Fixed 2026-07-24 by adding
+  `<FilesMatch>` `Require all denied` blocks (sensitive extensions incl. `.ini`, and any
+  `config.*`) — see the [1.0 back-end security standard](../../standards/backend-php.md).
+  **Action still owed:** rotate every secret in `config.production.ini` — the file was
+  reachable, so treat all of it as compromised. (Location only — no values recorded here.)
 - **SSO initiation + replay defense are open items** — see `features/saml-sso-auth.md`.
 - **Framework-level Sentry error reporting is an open gap.** Prod printed "Sentry is not
   installed" because `sentry/sentry` was missing from `composer.json` (added `^4.10`; sibling
@@ -99,6 +106,11 @@ Create `mvc/<folder>/<tool>/get.php` (copy `mvc/_TEMPLATE/get.php`), add one ent
   composer package must `require_once` the autoloader itself.
 
 ## Change history
+- 2026-07-24 — Fixed the config-file web-root exposure: `config.*.ini` was publicly readable via
+  the `!-f`-only front controller (`GET /config.production.ini` served it verbatim); added
+  `<FilesMatch>` deny blocks referencing the new 1.0 back-end security standard. Softened the
+  Critical-rules note from "team-accepted risk" to fixed-but-rotation-owed. Every secret in
+  `config.production.ini` still owes rotation (jcardinal)
 - 2026-07-24 — Added the SSO-gated **Design Demo Admin** tool at `/design` (`App_Design_Github`
   + `mvc/design/*` + namespaced assets + a `design` nav group), which publishes versioned demos
   into the `forward` repo over the GitHub API (see `features/design-demo-admin.md`). Noted the

package/knowledge/1.0/apps/tools/features/cloudfront-client-setup.md

@@ -0,0 +1,181 @@
+---
+title: CloudFront Client Setup
+framework: "1.0"
+repo: tools
+project: Tools
+client: shared
+type: feature
+status: active
+updated: 2026-07-24
+owners: [jcardinal]
+files:
+  - tools/_/app/devops/cloudfront.php
+  - tools/mvc/devops/cloudfront-clients/get.php
+  - tools/mvc/devops/cloudfront-clients/post.php
+  - tools/assets/js/cloudfront-clients.js
+  - tools/assets/css/cloudfront-clients.css
+  - tools/_/app/nav.php
+  - tools/_/app/frameworkindex.php
+  - tools/config.production.ini
+related:
+  - ../architecture.md
+  - ../features/persona-gated-navigation.md
+  - ../features/saml-sso-auth.md
+  - ../features/design-demo-admin.md
+  - ../../standards/backend-php.md
+---
+
+## Summary
+
+An SSO-gated admin tool at **`/devops/cloudfront-clients`** in the Tools 1.0 app that
+onboards a client onto **CloudFront + Route 53 across multiple AWS accounts** in one run.
+For each client slug × selected distribution it adds `{slug}.{baseDomain}` as a CloudFront
+**Alternate Domain Name** and creates the matching Route 53 **A + AAAA alias** records
+pointing at the distribution. It automates a repetitive, multi-account, error-prone manual
+onboarding step. Gated to the **`Development Team`** persona; has a **Dry-run** preview
+mode, a per-run slug cap, and an audit log line per non-dry-run attempt.
+
+## Key files / entry points
+
+- `_/app/devops/cloudfront.php` — class **`App_Devops_Cloudfront`** (all-static): the
+  single source of truth for account/distribution topology, AWS SDK client construction,
+  and all CloudFront + Route 53 domain logic.
+- `mvc/devops/cloudfront-clients/get.php` — route `/devops/cloudfront-clients` (page shell).
+- `mvc/devops/cloudfront-clients/post.php` — AJAX action endpoint (`action=process`).
+- `assets/js/cloudfront-clients.js`, `assets/css/cloudfront-clients.css` — self-guarded on
+  the `.cloudfront-clients-tool` root element, registered globally in
+  `_/app/frameworkindex.php`.
+- `_/app/nav.php` — new **`devops`** nav group, persona `['Development Team']`.
+- `config.production.ini` — documented, **commented placeholder** `[cloudfront_<accountId>]`
+  credential sections (location only — **no secret values** are stored in the knowledge base
+  or authored into tracked config here).
+
+Follows the same tool pattern as [Design Demo Admin](../features/design-demo-admin.md):
+`get.php` + `post.php` + a static `App_` class + per-tool namespaced js/css + one nav entry.
+The AWS SDK **v3** is vendored at `tools/vendor/autoload.php`; client construction mirrors
+`App_Talos_S3::client()` (explicit autoload-require guard, `class_exists` check, `try/catch`,
+`['ok' => ...]` array returns).
+
+## How it works
+
+### Topology is a single class constant
+
+`App_Devops_Cloudfront::CLOUDFRONTS` is the **only** source of truth for what can be
+onboarded, shaped as:
+
+```
+[ '<awsAccountId>' => [ '<distributionId>' => '<baseDomain>' ] ]
+```
+
+Adding or removing a distribution is done **solely** by editing this constant — no other code
+change is required.
+
+### Per slug × distribution
+
+1. Build the FQDN `{slug}.{baseDomain}`.
+2. **CloudFront alias:** `GetDistribution` → append the FQDN to `Aliases.Items` and bump
+   `Aliases.Quantity` → `UpdateDistribution` with `IfMatch = ETag`.
+3. **Route 53 records:** create **A** and **AAAA** alias records targeting the distribution's
+   DNS name. `AliasTarget.HostedZoneId` is the fixed AWS CloudFront constant
+   **`Z2FDTNDATAQYW2`**; `EvaluateTargetHealth = false`.
+
+### Route 53 zone lookup — by name, not list-all
+
+Zone resolution uses **`ListHostedZonesByName`** with the most-specific candidate walking down
+to the registrable apex (e.g. `compass.dev.sandbox.togasupply.com` → the `togasupply.com`
+zone). This jumps straight to the zone regardless of how many zones the account holds. The
+earlier `ListHostedZones` (list-all + longest-suffix match) approach **silently found
+nothing** and was replaced.
+
+### Record creation is INSERT-ONLY (never UPSERT)
+
+Existing A/AAAA records are read first (`existingAliasTypes` via `ListResourceRecordSets`); the
+tool creates **only the missing types** with the `CREATE` action. An existing record (e.g. a
+live production DNS entry) is **always left untouched**. UPSERT is deliberately never used —
+it would silently repoint a live production record.
+
+### Throttling + consistency gating
+
+- **Adaptive retries:** the SDK client is built with
+  `'retries' => ['mode' => 'adaptive', 'max_attempts' => 10]` because CloudFront
+  `UpdateDistribution` is aggressively rate-limited and a run fires many calls (was hitting
+  `Throttling: Rate exceeded`).
+- **Route 53 is gated on the CloudFront alias step succeeding for that item.** If the alias
+  fails (throttled, or `CNAMEAlreadyExists`), the Route 53 step is **skipped** so DNS is never
+  created pointing at a distribution that is not serving that hostname. Skips are **per item**;
+  the overall run continues past failures.
+
+### Safety rails
+
+- **Dry-run (preview only)** mode performs no writes.
+- **`MAX_SLUGS_PER_RUN = 100`** caps a single run.
+- Every **non-dry-run** attempt writes an **audit log** line including the acting user's email
+  (`App_Auth::currentUser()`).
+
+## Cross-account credential model
+
+Every account — **including** the production account `654654170868` that owns all Route 53
+zones — resolves to its **own** `[cloudfront_<accountId>]` config section through the single
+seam method **`credentialsForAccount()`**. Do **not** reuse the existing `[aws]` key for the
+prod account: `[aws]` is a **cross-account** key that only reaches the `654654170868` SQS queue
+from another account — it is **not an identity in `654654170868`**.
+
+On the actual EB server the **`ElasticBeanstalk-EC2-Instance-Profile`** role *is* in
+`654654170868`, so the prod account can use the instance role (no config key needed) once that
+role is granted: `route53:ListHostedZonesByName`, `route53:ChangeResourceRecordSets`,
+`route53:ListResourceRecordSets`, `cloudfront:GetDistribution`, `cloudfront:UpdateDistribution`.
+
+## Access control
+
+Behind Tools SSO; the nav action and page are gated to the **`Development Team`** persona (see
+[persona-gated-navigation](../features/persona-gated-navigation.md) and
+[saml-sso-auth](../features/saml-sso-auth.md)).
+
+## Client variations
+
+None — this is a shared internal DevOps tool. It *operates on* client slugs, but no single
+client owns or overrides it.
+
+## Gotchas / known issues
+
+- **`NoSuchDistribution` / zone-not-found means the WRONG ACCOUNT, not a permission problem.**
+  Permission failures return `AccessDenied`. A `NoSuchDistribution` or a missing
+  `togasupply.com` zone (when both demonstrably exist) means the call **authenticated into the
+  wrong account** — here, using the cross-account `[aws]` key against `654654170868`. Fix the
+  credential resolution, not the IAM policy. This is the key diagnostic for this tool.
+- **A CloudFront CNAME can live on only one distribution.** Re-adding an FQDN already attached
+  to a different distribution returns **`CNAMEAlreadyExists`**; the item is skipped (and Route 53
+  is skipped with it).
+- **Alternate domain names require a covering ACM certificate.** A wildcard cert covers only a
+  single label — `*.togasupply.com` does not cover `a.b.togasupply.com`. Ensure the distribution
+  has a cert covering the FQDN before adding it.
+- **Route 53 CloudFront alias records use the fixed `HostedZoneId` `Z2FDTNDATAQYW2`** (an AWS
+  global constant for all CloudFront alias targets — not the zone's own ID).
+- **1.0 promotes undefined-index warnings to a thrown `ErrorException`** that would abort the
+  whole "never fatally abort" run — all AWS-response array access is guarded. The SDK
+  client-builder `catch` is widened to **`\Throwable`** because the constructor can throw
+  `InvalidArgumentException`, not just `AwsException`.
+- **Credential exposure caveat.** This tool wields the prod IAM key, which amplified the impact
+  of the separate config-file web-root exposure fixed this session — see the 1.0 back-end
+  security standard and the Tools architecture Known issues. Every secret in
+  `config.production.ini` still owes rotation because the file was publicly readable.
+
+## Change history
+
+- 2026-07-24 — Built the CloudFront Client Setup tool (`App_Devops_Cloudfront` +
+  `/devops/cloudfront-clients` MVC route + namespaced assets + a `devops` nav group). Topology
+  is the `CLOUDFRONTS` class constant; per slug×distribution it adds a CloudFront alternate
+  domain name and Route 53 A+AAAA alias records (fixed `Z2FDTNDATAQYW2`). Cross-account
+  credentials resolve per-account via `credentialsForAccount()` (never reuse `[aws]` for the prod
+  account 654654170868 — instance role is used there). Route 53 lookup switched to
+  `ListHostedZonesByName`; record creation is INSERT-ONLY (never UPSERT); SDK adaptive retries
+  for CloudFront throttling; Route 53 gated on the alias step succeeding. Dry-run, per-run slug
+  cap (100), and per-attempt audit logging. (jcardinal)
+
+## Related docs
+
+- [Tools Architecture](../architecture.md)
+- [Design Demo Admin](../features/design-demo-admin.md)
+- [Back-End Coding Standards (1.0)](../../standards/backend-php.md)
+</content>
+</invoke>

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

@@ -5,7 +5,7 @@ project: Library
 client: shared
 type: standard
 status: active
-updated: 2026-07-09
+updated: 2026-07-24
 owners: [jcardinal, rgirish, mhammontree]
 files: []
 related:
@@ -453,6 +453,45 @@ $order->location = App_Page::getVarIfSet('installation');
 
 * Always use HTTPS to encrypt data in transit.
 
+### Web-root file exposure — deny config/secret files at the front controller
+
+A front controller whose only guard is a rewrite that skips existing files —
+`RewriteCond %{REQUEST_FILENAME} !-f` — is **not access control**. `!-f` means "if the
+requested path is a real file on disk, let Apache serve it directly rather than routing it
+through `index.php`." Any file that physically sits under the web root (config, `.env`,
+logs, SQL dumps, backups) is therefore served **verbatim** on a direct request. A plain
+`GET /config.production.ini` returns the raw file, secrets and all. This is a real breach
+class, not a theoretical one — it was found live in a 1.0 app this session.
+
+Deny sensitive files explicitly at the front controller, in addition to (not instead of)
+keeping them out of the web root:
+
+```apache
+# Deny by sensitive extension
+<FilesMatch "\.(ini|env|log|sql|sh|bak|dist)$">
+    Require all denied
+</FilesMatch>
+
+# Deny anything named config.* (config.production.ini, config.prod.ini, …)
+<FilesMatch "^config\.">
+    Require all denied
+</FilesMatch>
+```
+
+Rules:
+
+* **Keep config/secret files outside the web root where at all possible** — a file the web
+  server cannot reach cannot be served. Deny blocks are defense in depth for files that
+  must live inside the tree.
+* **The `!-f` rewrite is a router optimization, never a security boundary.** Do not rely on
+  it to hide anything.
+* **Anything that was ever web-readable is compromised and must be rotated** — assume it was
+  fetched. Rotate every credential in an exposed file; a deny rule added after the fact does
+  not un-expose what was already reachable.
+* **Audit every 1.0 app's front controller** for this pattern. If a `.htaccess`/vhost routes
+  through `index.php` on `!-f` alone with no `FilesMatch` deny blocks, it is exposed — add
+  the deny blocks and treat any secret-bearing file under the root as leaked.
+
 ### Authentication and Authorization
 
 * Use the framework's `App_Auth` / `App_Acl` for authentication and role-based access control; do not roll your own session/permission checks.

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

@@ -9,8 +9,9 @@
 | [Language Translation Layer (audience.language + sidecar tables)](features/language-translation-layer.md) | Serves the same TOGa data (Item title/description/longDescription, plus item **feature** text — `Features.name`, `ItemCategoryFeatureGroups.name`, `ItemFeatures | api2/Component/Api/V2/V2.php, api2/Component/Api/V2/Response/Response.php, _underscore/Model/Core/Setting.php, _underscore/Model/Core/RecordField.php, _underscore/Model/Core/DefaultGlobalSetting.php, _underscore/Model/Client/ItemTranslation.php, _underscore/Model/Client/FeatureTranslation.php, _underscore/Model/Client/ItemCategoryFeatureGroupTranslation.php, _underscore/Model/Client/ItemFeatureTranslation.php, dbchanges2/Client/2026-06-23a - ItemTranslations.sql, dbchanges2/Client/2026-06-23b - ItemTranslationsAcl.sql, dbchanges2/Client/2026-07-13a - FeatureTranslations.sql, dbchanges2/Client/2026-07-13b - FeatureTranslationsAcl.sql, dbchanges2/Core/2026-06-23a - RecordFieldsTranslationColumn.sql, dbchanges2/Core/2026-06-23b - ItemTranslationsRecord.sql, dbchanges2/Core/2026-07-13 - FeatureTranslationsRecord.sql |
 | [Nested FK object embedding is gated by the CHILD record's own ACL](features/nested-fk-acl-embedding.md) | When the V2 JSON engine serializes a foreign-key field into a **nested object** (in `getFullModelData()`, ~V2.php L6016-6060), it re-checks the **child** record | api2/Component/Api/V2/V2.php, dbchanges2/Client_Compass/2026-07-23b - PurchaseOrdersRecordReadAcl.sql |
 | [Nested-relationship writes & child matching (link vs. create)](features/nested-relationship-writes.md) | When a 2.0 API write payload (`POST`/`PUT`) contains a **nested related object** (e.g. | api2/Component/Api/V2/V2.php |
-| [Record Scripts (computed/aggregate /v2 endpoints — the authoring contract)](features/record-scripts.md) | In api2 you almost never write a controller. | api2/Component/Api/V2/V2.php, _underscore/Model/Team/Sprint.php |
+| [Record Scripts (computed/aggregate /v2 endpoints — the authoring contract)](features/record-scripts.md) | In api2 you almost never write a controller. | api2/Component/Api/V2/V2.php, _underscore/Model/Team/Sprint.php, _underscore/Query.php |
 | [POST + JSON-body args for scripted APIs](features/scripted-api-post-body-args.md) | The V2 engine can run a Record Script (scripted API) for a **POST** request, and a scripted API can receive its arguments from the **JSON request body** instead | api2/Component/Api/V2/V2.php |
+| [TOGa IQ Sprint Dashboard API (Record Scripts)](features/sprint-dashboard-api.md) | The internal **TOGa IQ sprint dashboard** is served in production by **six api2 Record Scripts** on `_Model_Team_Sprint` (`_underscore/Model/Team/Sprint.php`), | _underscore/Model/Team/Sprint.php, api2/Component/Api/V2/V2.php, dbchanges2/Core/2026-07-24a - SprintDashboardRecordScripts.sql, dbchanges2/Client_True/2026-07-24b - SprintDashboardScriptAcl.sql |
 | [Surface action-state via the surface=<slug> request option (M2M-safe)](features/surface-meta-option.md) | An opt-in V2 engine request option, `surface=<slug>`, that attaches per-record UI action state (`isVisible`/`isEnabled`) to a GET response **under `meta.surface | api2/Component/Api/V2/V2.php, _underscore/Model/Core/Surface.php |
 | [TableView row-filtering via apiWhereClause (options.where grammar, end to end)](features/tableview-apiwhereclause-row-filtering.md) | `TableViews.apiWhereClause` (TEXT, nullable) is the sanctioned, code-free way to restrict or exclude rows from a 2.0 table view. | api2/Component/Api/V2/V2.php, _underscore/Model/Client/TableView.php, toga2-supply/src/api/toga.ts |
 | [TableView field/column metadata (TableViewFields, hidden projected columns)](features/tableview-field-metadata.md) | The columns of a 2.0 table view are defined by DB metadata, not code. | _underscore/Model/Client/TableView.php, api2/Component/Api/V2/V2.php, dbchanges2/Client/2026-07-20 - ItemsUuidForPurchaseOrderItemsTableView.sql |

package/knowledge/2.0/apps/api2/features/record-scripts.md

@@ -6,12 +6,14 @@ project: API
 client: shared
 type: feature
 status: active
-updated: 2026-07-23
+updated: 2026-07-24
 owners: ["kyalamarthi"]
 files:
   - api2/Component/Api/V2/V2.php
   - _underscore/Model/Team/Sprint.php
+  - _underscore/Query.php
 related:
+  - ./sprint-dashboard-api.md
   - ./scripted-api-post-body-args.md
   - ./tableview-apiwhereclause-row-filtering.md
   - ../architecture.md
@@ -35,7 +37,13 @@ register one). For the POST + JSON-request-body variant (large argument values),
 Motivating example: `_Model_Team_Sprint::committedTile()` — a read-only dashboard tile over
 the internal TOGa IQ sprint (`Team` schema) data. **Decision recorded:** internal
 sprint/dashboard read endpoints are served from **api2 via a Record Script**, not by building
-a bespoke controller or standing the data up inside the talos / TOGa IQ app.
+a bespoke controller or standing the data up inside the talos / TOGa IQ app. This contract was
+subsequently validated by productionizing the whole sprint dashboard into six Record Scripts —
+see [TOGa IQ Sprint Dashboard API](./sprint-dashboard-api.md) for the concrete endpoint set.
+
+**The model class lives in `_underscore`, not api2.** `_Model_Team_Sprint` is
+`_underscore/Model/Team/Sprint.php`, pulled in at deploy — api2 has **no `Model/` directory**
+of its own. Write the static method in `_underscore`, not in the api2 repo.
 
 ## The method contract
 
@@ -51,9 +59,17 @@ Rules the engine enforces (see `getRecordScriptPhpMethod()` + the dispatch in
 - **Remaining parameters are named** and are filled from the **query string**. Each query-string
   key maps to the same-named PHP parameter; unmatched named args land in a `...$args` variadic
   if the method declares one. (`transactionId` and `api` keys are reserved and never mapped.)
-- **The return value is the envelope `data`.** Return an object/array; do not echo, and do not
-  return the bare success/error envelope — the engine wraps it.
+- **The return value becomes the envelope `data` — but nested under the route segment.** The
+  engine does `$outData[$requestedUuid] = method(...)` then `return (object)$outData`
+  (`V2.php` ~:4121, :6305), so the script's payload lands **under the script's route-segment
+  key**, not flat. `GET /v2/sprints/tile` yields `data: { tile: {…} }`, not `data: {…}`;
+  `campaigns/jobs` yields `data: { jobs: … }`. **A consumer must unwrap `data[<route>]`.** The
+  method itself still returns the raw object/array — do not echo, and never build the
+  success/error envelope yourself.
 - Invocation is effectively `$model::$phpMethod(...$args)`.
+- **No current-sprint (or any per-request context) middleware.** Unlike a hand-built app, the
+  `/v2` engine has no middleware that pre-resolves a "current" entity for a script. Each Record
+  Script must resolve its own context (e.g. the current sprint) inside the method.
 
 ## Running SQL inside a Record Script
 
@@ -66,7 +82,11 @@ then `->fetchRow()`) rather than going through model CRUD. Two framework realiti
   arguments arrive straight from the query string (user input), so this sanitization is
   mandatory — an unsanitized value in the query text is a SQL-injection hole. Treat
   `\_Database::escape()` + `(int)` casting as the required substitute for the prepared
-  statements `_Query` does not offer.
+  statements `_Query` does not offer. For a query-string arg drawn from a **fixed set** (an
+  enum-like `?category=`), the safest handling is a **value allowlist** — map the arg to a
+  trusted server-side constant (e.g. the sprint dashboard maps `?category=` to the
+  `_Model_Team_Task::WORK_TYPE__*` constants) and reject anything unrecognized, so no raw
+  user value ever reaches the SQL text.
 - **Query cache for "live" tiles.** A dashboard tile that must reflect current data should call
   `\_Database::useQueryCache(false)` before the query and **restore the previous flag**
   afterward (capture the value it returns and set it back), so it doesn't serve stale cached
@@ -104,6 +124,18 @@ grant under the per-client `Client_<Name>` folder. See the
 [api2 architecture — metadata CRUD engine](../architecture.md) for the surrounding Records
 metadata model.
 
+**Registration conventions** (confirmed against
+`Core/… - TrackingNumberReprintRecordScript.sql` + its `Client/… - …ScriptAcl.sql`):
+
+- Write the migrations **id-agnostic** — resolve FKs by looking the parent up **by route**,
+  and guard every insert with a **`NOT EXISTS`** subquery on its natural key so the file is
+  re-runnable and environment-agnostic (auto-increment ids differ per environment).
+- `Core.Records` carries the human-facing `name` / `description`.
+- The `AclRecordScripts` grant is a **CLIENT-DB** table. Put it in the specific
+  **`Client_<Name>`** folder for the tenant that should get the script — an internal-only
+  endpoint goes in `Client_True`. The generic **`Client/`** folder runs against **every**
+  tenant DB, so putting an ACL grant there hands the endpoint to all clients.
+
 ## Data source note (core DB hosts/credentials)
 
 The core cluster hosts and credentials this endpoint reads through are **not** documented here;
@@ -137,6 +169,15 @@ an `AclRecordScripts` grant in each client DB.
 
 ## Change history
 
+- 2026-07-24 — Refined the engine contract from productionizing the sprint dashboard (verified
+  in `V2.php` + `_underscore/Query.php`): the return value **nests under the route-segment key**
+  (`data[<route>]`, not flat — consumers must unwrap); there is **no current-sprint/context
+  middleware** (each script resolves its own context); the `_Model` class lives in
+  **`_underscore`** (pulled at deploy — api2 has no `Model/` dir). Added registration
+  conventions (id-agnostic resolve-by-route + `NOT EXISTS` guards; the `AclRecordScripts` grant
+  belongs in the tenant-specific `Client_<Name>` folder, never generic `Client/`, or it grants
+  every tenant) and the value-allowlist pattern for enum-like query args. Linked the new
+  [Sprint Dashboard API](./sprint-dashboard-api.md). (kyalamarthi)
 - 2026-07-23 — Initial documentation of the Record Script authoring contract (static
   `fn(&$api, ...namedParams)` on the record model; query-string → named args; return → `/v2`
   envelope `data`), the SQL specifics (`_Query` has no bound params → `_Database::escape()` +
@@ -149,6 +190,8 @@ an `AclRecordScripts` grant in each client DB.
 
 ## Related docs
 
+- [TOGa IQ Sprint Dashboard API](./sprint-dashboard-api.md) — the concrete six-endpoint set
+  that productionized this contract.
 - [POST + JSON-body args for scripted APIs](./scripted-api-post-body-args.md) — the POST /
   JSON-request-body variant for large argument values.
 - [api2 architecture](../architecture.md) — the metadata-driven /v2 CRUD engine that Record

package/knowledge/2.0/apps/api2/features/sprint-dashboard-api.md

@@ -0,0 +1,140 @@
+---
+title: TOGa IQ Sprint Dashboard API (Record Scripts)
+framework: "2.0"
+repo: api2
+project: API
+client: shared
+type: feature
+status: active
+updated: 2026-07-24
+owners: ["kyalamarthi"]
+files:
+  - _underscore/Model/Team/Sprint.php
+  - api2/Component/Api/V2/V2.php
+  - dbchanges2/Core/2026-07-24a - SprintDashboardRecordScripts.sql
+  - dbchanges2/Client_True/2026-07-24b - SprintDashboardScriptAcl.sql
+related:
+  - ./record-scripts.md
+  - ../architecture.md
+  - ../../worker2/features/team-sprint-management.md
+---
+
+## Summary
+
+The internal **TOGa IQ sprint dashboard** is served in production by **six api2 Record
+Scripts** on `_Model_Team_Sprint` (`_underscore/Model/Team/Sprint.php`), reading the `Team`
+schema on the core cluster. This replaced the prior session's local Node/React + Express
+(mysql2) stand-in — the prototype only ever proved the metric SQL; this is the real `/v2`
+path. **No api2 code was written**: the endpoints are the generic `/v2` engine plus the
+model methods (which live in `_underscore`) plus metadata rows seeded via dbchanges2.
+
+Producer/consumer split: **worker2** (`_Worker_Team_Sprint`) captures ClickUp sprint data
+into `DB_TEAM`; **api2** serves it read-only through these Record Scripts. The dashboard is
+internal-only — its `AclRecordScripts` grant is scoped to the **True** (staff) tenant.
+
+For the general authoring/registration contract these follow, see
+[Record Scripts](./record-scripts.md). For the metric definitions the SQL implements, see
+[Team Sprint Management](../../worker2/features/team-sprint-management.md).
+
+## The six endpoints
+
+All are `public static` methods on `_Model_Team_Sprint`, each run as `new \_Query($sql,
+\_underscore::DB_TEAM)` returning a raw object the `/v2` engine envelopes. Route is
+`GET /v2/sprints/<scriptRoute>` (record route `sprints` → `_Model_Team_Sprint`).
+
+| phpMethod | Purpose |
+|-----------|---------|
+| `current` | Resolve the current sprint (never hardcoded — see below). |
+| `sprintTile` | A single KPI tile; selected by **`?category=`** (Committed / Conditional / Stretch / Unplanned). |
+| `statusBreakdown` | Status-rollup pie (the SWITCH-into-five-buckets, default → Review). |
+| `workTypeBreakdown` | Work-type pie — `SUM(sprintPointsNow) GROUP BY workTypeNow`. |
+| `pointsByDev` | Sprint points by developer (Tasks ⋈ Tasks_Developers ⋈ Developers). |
+| `burndown` | Burndown over working days (CCU vs CCUS), `dayNumber` 1-based. |
+
+## Envelope nesting — data is under the route-segment key
+
+The engine nests a scripted return value **under the script's route segment**, it is not
+flattened: `GET /v2/sprints/tile` returns `data: { tile: {…} }`, and `GET /v2/sprints/current`
+returns `data: { current: {…} }`. A consumer must unwrap `data[<route>]`, not read `data`
+directly. (Same shape as the live `campaigns/jobs` script → `data: { jobs: … }`.) This is the
+single biggest gotcha for the frontend cutover.
+
+## Current-state (Power BI) scoring — deliberate, not canonical
+
+These endpoints reproduce the **Power BI current-state** numbers the dashboard was validated
+against: done = `dtDone IS NOT NULL` and category from `workTypeNow`. They do **not** use the
+canonical **at-lock** sprint scoring (`workTypeAtLock` + `statusNow IN (STATUS_IN__DONE)`) used
+by the model's `_score*` / `_reliabilityScore` helpers. Reconciling current-state vs canonical
+for a leadership view is a **separate, deliberate decision left open** — do not assume these
+tiles agree with sprint scores. See the two-definitions section in
+[Team Sprint Management](../../worker2/features/team-sprint-management.md).
+
+Verified against live prod (sprint 83): the **Conditional** KPI tile reads `workTypeAtLock`
+(72 pts) while the work-type pie reads `workTypeNow` (67 pts) — a real at-lock-vs-now
+divergence, by design, not a bug.
+
+## SQL safety (no bound params in `_Query`)
+
+`_Query` has no `?`/`:name` binding, so injection safety is by construction, matching the
+model's existing `_score*` helpers:
+
+- The sprint number is `(int)`-cast.
+- The `?category=` query-string value is **not interpolated raw** — it is mapped through a
+  value allowlist to the `_Model_Team_Task::WORK_TYPE__*` constants; an unrecognized category
+  is rejected, never placed into SQL.
+- Every other column/value in the query text is a trusted server-side constant.
+
+Work-type values in the `Team` schema are stored **UPPERCASE** (`COMMITTED` / `CONDITIONAL`
+/ `STRETCH` / `UNPLANNED`); the productionized code sources them from the
+`_Model_Team_Task::WORK_TYPE__*` constants rather than mixed-case literals (the prototype's
+`'Committed'` only worked because the collation is case-insensitive).
+
+## Registration (two dbchanges2 files)
+
+Registered as metadata, not a code deploy (see [Record Scripts](./record-scripts.md) for the
+full contract). Two migrations, both **id-agnostic resolve-by-route + `NOT EXISTS` guards** so
+they are re-runnable and environment-agnostic:
+
+- `dbchanges2/Core/2026-07-24a - SprintDashboardRecordScripts.sql` — one `Core.Records` row
+  (`route 'sprints'` → `_Model_Team_Sprint`, with `name`/`description`, `aclDatabase = 'CORE'`
+  because `Team` is co-located on the core cluster) + six `Core.RecordScripts` rows.
+- `dbchanges2/Client_True/2026-07-24b - SprintDashboardScriptAcl.sql` — the
+  `Client.AclRecordScripts` grant. It is a **CLIENT-DB** table, so it lives in the per-client
+  **`Client_True`** folder (roles **1 / 3 / 4**). Putting it in the generic `Client/` folder
+  would grant the internal dashboard to **every** tenant.
+
+## Data source note
+
+The core-cluster hosts/credentials the `Team` reads flow through live in api2 `Config/*.ini`
+(`[database]`) — never in knowledge or code.
+
+## Open items (frontend cutover)
+
+- Frontend `fetchEnvelope` must unwrap `data[<route>]` (see nesting above).
+- Replace the prototype's empty-placeholder `AUTH_TOKEN` with real Bearer-JWT auth, and
+  reconcile the ACL role (True 1/3/4) to the dashboard's auth identity.
+- Verify `Tasks_Developers` has a `UNIQUE (taskId, developerId)` key plus sprint/workType
+  indexes.
+- `pointsByDev` filters to a first-name allowlist (excludes non-roster devs) — keep that
+  allowlist in sync with the roster.
+
+## Change history
+
+- 2026-07-24 — Productionized the TOGa IQ sprint dashboard as six api2 Record Scripts on
+  `_Model_Team_Sprint` (`current`, `sprintTile ?category=`, `statusBreakdown`,
+  `workTypeBreakdown`, `pointsByDev`, `burndown`), replacing the local Express/mysql2
+  prototype with no api2 code change. Documented the **route-segment envelope nesting**
+  (`data[<route>]`), the deliberate Power BI current-state scoring (Conditional tile
+  `workTypeAtLock` 72 pts vs work-type pie `workTypeNow` 67 pts on sprint 83), UPPERCASE
+  work-type values sourced from `_Model_Team_Task::WORK_TYPE__*`, the `?category=` allowlist
+  as the `_Query` injection defense, and the two-file dbchanges2 registration (Core records
+  + `Client_True` ACL grant to roles 1/3/4). (kyalamarthi)
+
+## Related docs
+
+- [Record Scripts](./record-scripts.md) — the authoring/registration contract these follow.
+- [Team Sprint Management & Reporting](../../worker2/features/team-sprint-management.md) — the
+  worker2 producer and the metric definitions the SQL implements.
+- [api2 architecture](../architecture.md) — the metadata-driven `/v2` engine.
+</content>
+</invoke>

package/knowledge/2.0/apps/worker2/features/team-sprint-management.md

@@ -186,9 +186,11 @@ All sprint state lives in the Team database (`_underscore::DB_TEAM`). Core table
 **Column vocabularies & datetime columns (dashboard-relevant).** For current-state reporting the
 exact values matter:
 
-- **`workTypeNow` / `workTypeAtLock`** — enum `COMMITTED / CONDITIONAL / STRETCH / UNPLANNED`.
-  MySQL string comparison is **case-insensitive** by default, so `'Committed'`/`'STRETCH'`/etc.
-  all match regardless of case.
+- **`workTypeNow` / `workTypeAtLock`** — enum `COMMITTED / CONDITIONAL / STRETCH / UNPLANNED`,
+  stored **UPPERCASE** in prod. MySQL string comparison is **case-insensitive** by default, so
+  a mixed-case literal (`'Committed'`) still matches — but production code should source these
+  from the **`_Model_Team_Task::WORK_TYPE__*` constants** rather than typing literals (the api2
+  sprint-dashboard Record Scripts do this).
 - **`statusNow` / `statusAtLock` / `statusAtEnd`** — free-form varchar, values stored
   **lower-case**: `complete`, `to do`, `in progress`, `stage review`, `hotfix review`,
   `back-end review`, `ui review`, `on hold`, `roadblocked`, `awaiting client`, `rework`,
@@ -319,7 +321,9 @@ Points = `sprintPointsNow`; each task is assigned **one** segment via a SWITCH e
 3. else → the task's **`workTypeNow`** value (Committed / Conditional / Unplanned).
 
 Joined `Tasks → Tasks_Developers → Developers` and grouped by developer. Because the join is
-many-to-many, each assigned developer is credited the task's **full** `sprintPointsNow`.
+many-to-many, each assigned developer is credited the task's **full** `sprintPointsNow`. The
+chart also filters developers to a **first-name allowlist** (the active roster), so non-roster
+developers who happen to be assigned are excluded from the per-dev breakdown.
 
 ### Sprint Burndown (over working days)
 Plotted over **working days only** (Mon–Fri, ~10 per two-week sprint; call the count `N`,
@@ -350,12 +354,21 @@ middleware defaults every tile/chart endpoint to it when no `?sprint=` is suppli
 > [per-client database connections](../../_underscore/features/per-client-database-connections.md))
 > by a local Node/React + Express (mysql2) prototype that stands in for the api2 `/v2` engine and
 > returns the standard api2 envelope. The prototype's DB credentials live in an **uncommitted
-> `.env`** (never in the repo or this doc). When productionized, the tiles become api2 Record
-> Scripts registered via **dbchanges2** — see
-> [Record Scripts](../../api2/features/record-scripts.md).
+> `.env`** (never in the repo or this doc). The dashboard has since been **productionized**:
+> the tiles/charts are now six api2 Record Scripts on `_Model_Team_Sprint`, registered via
+> **dbchanges2** and granted to the True tenant — see
+> [TOGa IQ Sprint Dashboard API](../../api2/features/sprint-dashboard-api.md) and the general
+> [Record Scripts](../../api2/features/record-scripts.md) contract. The Express stand-in is
+> retired.
 
 ## Change history
 
+- 2026-07-24 — Productionized the dashboard: the metric definitions above are now served by six
+  api2 Record Scripts on `_Model_Team_Sprint` (see
+  [Sprint Dashboard API](../../api2/features/sprint-dashboard-api.md)), retiring the Express
+  prototype. Refined the data model: work-type values are stored **UPPERCASE** and should be
+  sourced from the `_Model_Team_Task::WORK_TYPE__*` constants; the Sprint-Points-By-Dev chart
+  filters to a **first-name roster allowlist**. (kyalamarthi)
 - 2026-07-24 — Documented the full **Power BI dashboard metric definitions (DAX → SQL)** for the
   TOGa IQ sprint dashboard: KPI tiles by work type (with the non-uniformity that **Conditional
   filters on `workTypeAtLock`** while Committed/Stretch/Unplanned filter on `workTypeNow`), the

package/knowledge/INDEX.md

@@ -13,13 +13,13 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 - **walmarttechservices** (Walmart Tech Services) — 1 doc(s) → [1.0/apps/walmarttechservices/INDEX.md](1.0/apps/walmarttechservices/INDEX.md)
 - **test** (Test) — 13 doc(s) → [1.0/apps/test/INDEX.md](1.0/apps/test/INDEX.md)
 - **toga** (TOGa) — 2 doc(s) → [1.0/apps/toga/INDEX.md](1.0/apps/toga/INDEX.md)
-- **tools** (Tools) — 9 doc(s) → [1.0/apps/tools/INDEX.md](1.0/apps/tools/INDEX.md)
+- **tools** (Tools) — 10 doc(s) → [1.0/apps/tools/INDEX.md](1.0/apps/tools/INDEX.md)
 
 ## 2.0 framework
 
 - **_underscore** (_Underscore) _(framework core)_ — 38 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
 - **worker2** (Worker) — 31 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
-- **api2** (API) — 16 doc(s) → [2.0/apps/api2/INDEX.md](2.0/apps/api2/INDEX.md)
+- **api2** (API) — 17 doc(s) → [2.0/apps/api2/INDEX.md](2.0/apps/api2/INDEX.md)
 - **dbchanges2** (Database Changes) _(framework core)_ — 3 doc(s) → [2.0/apps/dbchanges2/INDEX.md](2.0/apps/dbchanges2/INDEX.md)
 - **toga2-supply** (TOGa Supply) — 3 doc(s) → [2.0/apps/toga2-supply/INDEX.md](2.0/apps/toga2-supply/INDEX.md)
 - **saml** (SAML SSO Gateway) — 3 doc(s) → [2.0/apps/saml/INDEX.md](2.0/apps/saml/INDEX.md)

package/knowledge/clients/true/profile.md

@@ -6,12 +6,13 @@ apps:
   - tools
   - worker2
   - dbchanges2
+  - api2
 project: _Underscore
 client: true
 type: profile
 status: active
-updated: 2026-06-29
-owners: [jcardinal]
+updated: 2026-07-24
+owners: [jcardinal, kyalamarthi]
 files: []
 related:
   - clients/true/features/users-personas-data-model.md
@@ -28,6 +29,11 @@ by staff role (e.g. the planned Toolbox app) reads its `Users` / `Personas` mode
 - **Client identifier:** `True`
 - **SSO mapper:** `_Model_True_ClientAuthentication` (base; matches by email from NameID)
 
+The internal **TOGa IQ sprint dashboard** is served to True from **api2** as six Record
+Scripts on `_Model_Team_Sprint` (over the `Team` schema), with the `AclRecordScripts` grant
+scoped to True roles 1/3/4 — hence `api2` is in this client's `apps`. See
+[Sprint Dashboard API](../../2.0/apps/api2/features/sprint-dashboard-api.md).
+
 The **Tools** app (1.0; repo `tools`) authenticates True users via **SSO** through
 `saml.togahub.com` and reads the `Client_True` DB **read-only** to gate its internal tooling by
 staff persona (see `1.0/apps/tools/`). Its gateway return domain is registered in `Core.Domains`

package/package.json

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