toga-ai 1.0.106 → 1.0.107

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

@@ -4,3 +4,4 @@
 |-----|---------|-------|
 | [API (api2 / TOGa API v2) Architecture](architecture.md) | `api2` is the backend powering the public **TOGa 2.0 API**. | api2/Controller/Index.php, api2/Component/Api/V2/V2.php, api2/Component/Api/Cxml/Cxml.php, api2/Component/Api/V2/Response/Response.php, api2/Config/ |
 | [AWS CodePipeline Deployment via CodeConnections (GitHub → Elastic Beanstalk)](workflows/codepipeline-codeconnections-deploy.md) | 2.0 apps (`api2`, `_underscore`) are deployed through **AWS CodePipeline**. |  |
+| [New Environment Configuration & Provisioning (api2)](workflows/environment-configuration-and-provisioning.md) | What it takes for a 2.0 API environment (e.g. | api2/Config/<environment>.ini, api2/Controller/Index.php, dbchanges2/Core/2026-06-16a - DatabaseHosts for new QA QC stage demo environments.sql, _underscore/Route.php |

package/knowledge/2.0/apps/api2/workflows/environment-configuration-and-provisioning.md

@@ -0,0 +1,92 @@
+---
+title: New Environment Configuration & Provisioning (api2)
+framework: "2.0"
+repo: api2
+project: API
+client: shared
+type: workflow
+status: active
+updated: 2026-06-16
+owners: ["jcardinal"]
+files:
+  - api2/Config/<environment>.ini
+  - api2/Controller/Index.php
+  - dbchanges2/Core/2026-06-16a - DatabaseHosts for new QA QC stage demo environments.sql
+  - _underscore/Route.php
+related: []
+---
+
+## Summary
+What it takes for a 2.0 API environment (e.g. `qc-security`, `qa-task`, `stage`) to actually
+serve requests. Three independent things must all be correct, or `/v2/...` calls fail — often
+with a **misleading** error. This documents the config conventions, the `Core.DatabaseHosts`
+data the framework needs, and the database seeding step, plus the diagnostic gotcha that masks
+the real cause.
+
+## Steps (to stand up a new environment)
+
+1. **Create `api2/Config/<environment>.ini`.** Copy an existing all-in-one env file
+   (e.g. `qc-security.ini`) and change **only**:
+   - `[database]` and `[database1]` → `hostname` = the env's DB cluster endpoint.
+   - `[api]` → `_` and `worker` = the env's API/worker base URLs.
+   Leave everything else (cloud keys, fedex, netsuite, ups, calcom, etc.) as-is. Match the
+   file's existing **CRLF** line endings — a whole-file LF flip buries the real diff.
+
+2. **Use the correct host naming convention** (load-bearing — see Gotchas):
+   - **DB host:** `<specific>.<family>.database.togahub.com` — e.g. `security.qc...`,
+     `task.qa...`. The specific name comes **first**, the family (`qa`/`qc`) second.
+     `stage`/`demo` are single-label: `stage.database.togahub.com`.
+   - **API/worker base:** `https://api.<dbprefix>.togahub.com/v2` and
+     `https://worker.<dbprefix>.togahub.com`, where `<dbprefix>` is the DB host minus
+     `.database` (e.g. DB `security.qc.database...` → `api.security.qc.togahub.com`).
+
+3. **Register `Core.DatabaseHosts` rows** for the environment (via a `dbchanges2/Core`
+   migration). Non-prod environments are **all-in-one**: a single cluster holds `Core` +
+   every `Client_`/`Logs_`/`Archive_` DB. So insert **one row per database**, `regionId = NULL`,
+   with `hostCluster = hostWriter = hostReader` = the single endpoint. Resolve `environmentId`
+   by `Environments.slug` and `databaseId` from the Core's own `Databases` table so the migration
+   is portable across every Core; guard with `NOT EXISTS` for idempotency. (Production differs:
+   per-family clusters and per-region reader rows.)
+
+4. **Seed the cluster.** A brand-new RDS cluster has only system schemas. `Core` and the client
+   DBs must be provisioned and the `dbchanges2` migrations applied before the app can connect.
+   Until then, every request throws on the first Core query.
+
+## Systems involved
+- **api2** — `Config/<env>.ini` (DB + API hosts); `Controller/Index.php::api()` registers `Core`
+  from `[database]` then dispatches by hostname.
+- **_underscore** — boot/routing; reads `Core.Environments` + `Core.DatabaseHosts` to resolve
+  region-aware connections.
+- **dbchanges2/Core** — the migration that populates `Core.DatabaseHosts` per environment.
+- **Core DB** — `Environments`, `Databases`, `DatabaseHosts`, `Regions` drive resolution.
+
+## Edge cases & escalation — diagnosing a broken environment
+
+**Symptom:** a fatal like
+`Uncaught Exception: Failed to determine how to render view for route '/v2/auth/api' ... Route.php:525`.
+
+**This message is misleading — it is almost never about views.** `_Controller_Index::api()`
+threw an `Exception` (e.g. the `Core` DB connection/query failed), and `_underscore/Route.php`'s
+dispatch **catches `Exception`, silently rolls back, leaves the controller response unset**, then
+falls through to its view-render path and throws the generic "Failed to determine how to render
+view" error. The real exception is swallowed. When the same codebase works in `production` but
+fails in a new environment, suspect **environment config / Core DB**, not the view layer.
+
+Diagnostic order:
+1. Compare the env's `[database] hostname` against the `<specific>.<family>.database.togahub.com`
+   convention — a reversed host (e.g. `qc.security...` instead of `security.qc...`) won't resolve.
+   Verify with `nslookup` / PHP `mysqli_connect`.
+2. Connect to the resolved host and `SHOW DATABASES` — confirm `Core` actually exists (a fresh
+   cluster has only `information_schema/mysql/performance_schema/sys` → not seeded yet).
+3. Confirm `Core.DatabaseHosts` has rows for this `environmentId` (Core Logs DB id is `11`).
+
+## Change history
+- 2026-06-16 — Documented after fixing `qc-security`: `[database] hostname` was reversed
+  (`qc.security...`), which threw on Core connect and surfaced as the Route.php:525 view fatal.
+  Added the `2026-06-16a` Core migration registering `DatabaseHosts` for the stage/demo/qa-*/qc-*
+  all-in-one environments, and created the matching `Config/*.ini` files. (jcardinal)
+
+## Related docs
+- `2.0/apps/api2/architecture.md` — host dispatch, transaction/logging boundary.
+- `2.0/apps/_underscore/architecture.md` — environment→host table, DB resolution, boot sequence.
+- `2.0/apps/api2/workflows/codepipeline-codeconnections-deploy.md` — deploy pipeline.

package/knowledge/INDEX.md

@@ -16,7 +16,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 
 - **_underscore** (_Underscore) _(framework core)_ — 7 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
 - **worker2** (Worker) — 6 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
-- **api2** (API) — 2 doc(s) → [2.0/apps/api2/INDEX.md](2.0/apps/api2/INDEX.md)
+- **api2** (API) — 3 doc(s) → [2.0/apps/api2/INDEX.md](2.0/apps/api2/INDEX.md)
 - **dbchanges2** (Database Changes) _(framework core)_ — 1 doc(s) → [2.0/apps/dbchanges2/INDEX.md](2.0/apps/dbchanges2/INDEX.md)
 - **toga2-supply** (TOGa Supply) — 2 doc(s) → [2.0/apps/toga2-supply/INDEX.md](2.0/apps/toga2-supply/INDEX.md)
 - **saml** (SAML SSO Gateway) — 2 doc(s) → [2.0/apps/saml/INDEX.md](2.0/apps/saml/INDEX.md)

package/package.json

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