toga-ai 1.0.172 → 1.0.174

package/knowledge/1.0/apps/test/features/toga2-client-onboarding-sql.md

@@ -6,48 +6,70 @@ project: Test
 client: shared
 type: feature
 status: active
-updated: 2026-06-16
-owners: [jcardinal]
+updated: 2026-06-23
+owners: [jcardinal, mhammontree]
 files:
   - test/team/generate_toga2_onboarding_sql.php
 related:
   - ../architecture.md
   - ./toga2-user-cross-client-access-sql.md
+  - ../../../2.0/apps/dbchanges2/workflows/client-onboarding.md
 ---
 
 ## Summary
 
 `team/generate_toga2_onboarding_sql.php` generates the SQL needed to **onboard a new client**
 onto the 2.0 platform. Runs on the **1.0 `App_` framework**
-(`App_Framework_Sandbox::initialize()`), but the SQL it produces targets the **2.0** client
-databases.
+(`App_Framework_Sandbox::initialize()`), but the SQL it produces targets the **2.0** Core and
+client databases. It is the *insert-generation* half of onboarding; the schema/blank half lives
+in dbchanges2 (see the [2.0 client onboarding workflow](../../../2.0/apps/dbchanges2/workflows/client-onboarding.md)).
 
 ## How it works
 
-Configure the `const` block, then run; the script emits the onboarding SQL to stdout for review.
+Configure the `const` block, then run; the script emits the onboarding SQL to stdout (`<pre>`).
 
 Key configuration:
-- `CLIENT_NAME` — formal client name, proper case (e.g. `'The Coca-Cola Company'`).
-- `CLIENT_IDENTIFIER` — PascalCase, no spaces (e.g. `'Cocacola'`).
+- `CLIENT_NAME` — formal client name, proper case (e.g. `'Fordham University'`).
+- `CLIENT_IDENTIFIER` — PascalCase, no spaces (e.g. `'Fordham'`) → drives `Client_<Id>` etc.
 - `CLIENT_SUBDOMAIN_IDENTIFIER` — lowercase, no spaces; the email domain without TLD.
 - `CLIENT_EMAIL_DOMAINS` — array of permitted email domains **with** TLD.
-- `SHOULD_CREATE_AGILANT_API` — when true, also creates the Agilant API user and api-roles.
+- `SHOULD_CREATE_AGILANT_API` — when true, creates the internal **Agilant** API key + api-roles.
+- `CREATE_CLIENT_API_NAME` — string (e.g. `'Fordham'`) to also create the **client** API key, or `null` to skip.
+- `RELATIVE_PATH_TO_DBCHANGES2`, `SHOULD_CONSOLIDATE` — declared but **not yet implemented** (no
+  consolidation logic in this script; the blank/consolidation lives in dbchanges2).
 
-Platform topology baked into the script:
-- `DATABASE_PREFIXES = ['Client', 'Logs', 'Archive']` — the three DB families a client gets.
-- `ENVIRONMENTS__DATABASE_PREFIXES__CLUSTERS` — per-environment (`dev` / `beta` / `production`)
-  host endpoints for each DB prefix. Production uses a global Aurora cluster with separate
-  writer/reader endpoints (`writer.client.database.togahub.com` / `reader1.client.database.togahub.com`);
-  dev/beta fall back to a single cluster (reader = writer).
+What it emits (UUIDs via `App_Misc::generateUUID()`; it does not touch the DB):
+- **Core inserts** → run on the **core cluster**: `Core.Databases` (Client_/Logs_/Archive_),
+  `Core.Clients`, `Core.Domains` (every app × env), `Core.ClientEmailDomains`, `Core.DatabaseHosts`
+  (prod null-region + 3 regions).
+- **Client inserts** → run on the **client cluster** (`Client_<Id>`): `Apis` + `Apis_Roles`.
+  Note: the `Apis` rows live in the **client** DB, not Core.
+
+## Output split (core vs client clusters)
+
+The script emits one combined blob; for deployment, split it: Core-table inserts to the core
+cluster, the `Apis`/`Apis_Roles` inserts to the client cluster (against `Client_<Id>`, which must
+already have the `Base`/`API` roles from the blank seed so the `Apis_Roles` lookup resolves).
 
 ## Gotchas
 
+- **`Apis_Roles` needs a unique uuid per row.** The role-link insert is
+  `INSERT … SELECT <uuid>, …, r.id FROM Roles WHERE r.name IN ('Base','API')` — that SELECT returns
+  **2 rows**, so a hardcoded literal uuid makes both rows share it → `Duplicate entry … for key
+  'Apis_Roles.uuid'`. Use MySQL **`UUID()`** in the SELECT so each row gets its own. (Fixed
+  2026-06-23; previously bit every client where both roles exist.)
+- **Secrets in output.** The generated `Apis` rows contain real `secret` values. **Never commit**
+  the client-insert file (or any artifact containing it) to a repo — run it in prod and distribute
+  the secret out-of-band. Core inserts are secret-free and safe to commit.
 - The cluster/endpoint map is environment infrastructure encoded as constants — if RDS endpoints
-  change, this script must be updated.
-- Identifiers have strict casing rules (formal vs PascalCase vs lowercase-subdomain); getting
-  them wrong produces inconsistent DB/identity records.
+  change, update the script.
+- Identifiers have strict casing rules (formal vs PascalCase vs lowercase-subdomain).
 - Output is SQL to run manually — review before executing against production.
 
 ## Change history
 
+- 2026-06-23 — Fixed `Apis_Roles` duplicate-uuid bug (use `UUID()` per row); fixed PHP 8 fatal from
+  an unquoted `CREATE_CLIENT_API_NAME` constant; implemented the previously-unused client-API block
+  (`CREATE_CLIENT_API_NAME`) so it emits both the Agilant and client keys; documented core/client
+  cluster split and the secret-handling rule. (mhammontree)
 - 2026-06-16 — Initial capture.

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

@@ -4,5 +4,6 @@
 |-----|---------|-------|
 | [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/ |
 | [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 |
+| [Tickets API (/v2/tickets)](features/tickets-api.md) | The generic ticket endpoint of the 2.0 REST API. | Component/Api/V2/V2.php |
 | [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/features/tickets-api.md

@@ -0,0 +1,72 @@
+---
+title: Tickets API (/v2/tickets)
+framework: "2.0"
+repo: api2
+project: API
+client: shared
+type: feature
+status: active
+updated: 2026-06-23
+owners: ["mhammontree"]
+files:
+  - Component/Api/V2/V2.php
+related:
+  - ../architecture.md
+  - ../../dbchanges2/workflows/client-onboarding.md
+---
+
+## Summary
+
+The generic ticket endpoint of the 2.0 REST API. Tickets are a metadata-driven **Record**
+(`tickets` → `_Model_Client_Ticket`, `aclDatabase = CLIENT`), so they're created/updated/read like
+any record: `POST/PUT/GET /v2/tickets` (and `/v2/tickets/{uuid}`). PC Matic instead uses
+`/v2/entitlement-tickets` (entitlement-wrapped); plain clients (e.g. Fordham) use `/v2/tickets`
+with ticket fields at the top level.
+
+## Auth & request conventions
+
+- **Base URL** `https://api.togahub.com/v2` (sandbox `https://api.client.sandbox.togahub.com/v2`).
+- **Auth**: `POST /v2/auth/api {client, api, secret}` → `data.tokens.access` (Bearer, ~1h) +
+  `data.tokens.refresh` (~30d). `client` = `Core.Clients.uuid`, `api`/`secret` = the client's
+  `Client_<Id>.Apis` row. Refresh via `POST /v2/auth/refresh` with the refresh token as Bearer.
+- Every request needs a **unique `transactionId`** query param (reuse → `EV-5`).
+- Response envelope: `{transactionId, isSuccess, status, error, messages[], meta{}, data{}}`. A
+  created/read ticket comes back under **`data.tickets`** (not bare `data`).
+
+## How it works (write model)
+
+- **Related objects are nested and resolved by a natural identifier**, not numeric IDs — and **each
+  field has its own identifier set**:
+  - `urgency` → `name` / `weight` / `uuid` (**NOT `code`**)
+  - `ticketStage` → `code`
+  - `ticketType`, `ticketTopic` → `name`
+  Sending an identifier a field doesn't recognize returns **`EV-12`** (the error lists the valid
+  identifier fields). These are **MATCH** (must-exist) references — the value must already exist in
+  the client's reference data.
+- **Inline-created** objects (safe to send without pre-existing data): `address` (CREATE),
+  `contact`/`contactPhoneNumber`/`location`/`reportedByContact` (MATCH_UPSERT).
+- **Child arrays** created inline: `ticketNotes[]`, `ticketFiles[]`, `ticketUnits[]`, `ticketItems[]`,
+  `ticketUsers[]`, `ticketServiceQuestionAnswers[]`.
+- Add a note to an existing ticket via the nested route `POST /v2/tickets/{uuid}/ticket-notes`.
+- `number` is auto-generated (`TK`-prefixed, starts `TK100000`).
+
+A minimal create needs only `shortDescription`/`longDescription` (+ optional `impact`, `ticketNotes`);
+the FK references are all nullable.
+
+## GET / filtering
+
+`GET /v2/tickets` supports `fields`, `where`, `join`/`ojoin`, `sort`, `group`, pagination
+(`page`/`recordsPerPage`), `depth`. To fetch tickets for a contact on the generic flow, join the
+ticket's own contact: `join=Contacts@Contacts:Contacts.id=Tickets.contactId&where=(Contacts.uuid:eq:<uuid>)`.
+(PC Matic instead joins through Entitlements — only valid for its entitlement flow.)
+
+## Gotchas
+
+- **`urgency` matches by `name`, not `code`** — the most common `EV-12` cause.
+- **Reference data must exist** — a newly onboarded client has no Urgencies/TicketTypes/TicketStages/
+  TicketTopics until seeded, so those fields can't be referenced yet (see the onboarding workflow).
+- **Response is under `data.tickets`** — not bare `data`.
+
+## Change history
+
+- 2026-06-23 — Initial capture from the Fordham ticket integration + customer docs (TRUE-79699). (mhammontree)

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

@@ -3,3 +3,4 @@
 | Doc | Summary | Files |
 |-----|---------|-------|
 | [Database Changes (dbchanges2) Repository Architecture](architecture.md) | `dbchanges2` is the **schema-migration / SQL change-set repository** for the entire 2.0 platform. | Core/, Client/, Client_<Tenant>/, Logs/, Logs_Client/, _modules/ |
+| [2.0 New-Client Onboarding (manual process)](workflows/client-onboarding.md) | How to manually stand up a new 2.0 client (tenant). | Client/, Client_<Tenant>/, Core/, Logs_Client/ |

package/knowledge/2.0/apps/dbchanges2/architecture.md

@@ -6,7 +6,7 @@ project: Database Changes
 client: shared
 type: architecture
 status: active
-updated: 2026-06-19
+updated: 2026-06-23
 owners: [jcardinal, mhammontree]
 files:
   - Core/
@@ -36,7 +36,9 @@ is the intended execution order.
 **Critical rules:** every new `.sql` file **must** be named `YYYY-MM-DD<letter> - <Description>.sql`
 with a **mandatory lower-case letter** right after the date (`a` for the first file of that day
 in a folder, then `b`, `c`, …). One folder per database; place client changes under the matching
-`Client_<Name>` folder. Never edit an already-run migration — add a new dated file instead.
+`Client_<Name>` folder. Never edit an already-run migration — add a new dated file instead. The
+`Client/` **blank must carry the baseline DATA seed** (roles, full ACL, reference/lookup tables,
+UI config) — **not just schema**; a schema-only blank produces non-functional clients.
 
 ## File naming convention (the execution contract)
 
@@ -124,6 +126,31 @@ already-applied change files moved aside to keep the live list short. Present un
 typically bucketed as `FILES BEFORE <date>` (or by year under `Core/`). **Never** rely on a
 file inside `HISTORIC` running; **never** add new changes there.
 
+## The Client blank: baseline data + consolidation
+
+`Client/<DATE>-BLANK_CLIENT_DATABASE.sql` (the **latest-dated** one is the current blank) is the
+starting point for every new tenant. It is **not schema-only** — it must also carry the **baseline
+data seed**: the standard roles (`Base`, `Developer`, `API`, `Public`), the full ACL
+(`AclRecordPermissions`/`AclFieldPermissions`/`AclRecordExpressions`/`AclLogicGroups`/…), the
+reference/lookup tables (countries, states, statuses, types, …), and UI config (`TableViews` + fields,
+`SectionRecordFields`). A client built from a **schema-only** blank has no roles/ACL and **cannot
+authorize** — this regressed once (the blank was reduced to `EmailTemplates`-only), which is why a new
+client appeared to onboard but failed at the API.
+
+**Consolidation lifecycle** (folding loose `Client/` changes back into a fresh blank):
+1. The loose `Client/` files must **already be applied to every existing client DB** before they're
+   archived (otherwise the new blank diverges from live clients). This is done manually as the files
+   are created.
+2. Rebuild the blank from the **current clean schema + the baseline data** and `mysqldump` **WITH
+   data** (never `--no-data` — that is exactly how the seed was lost). Keep secret-bearing tables
+   (`Apis`) **out** of the blank.
+3. `git mv` the old blank + the consolidated loose files into `Client/HISTORIC/FILES BEFORE <DATE>/`,
+   leaving `Client/` with only the new dated blank.
+
+**Applying loose files** requires `SET FOREIGN_KEY_CHECKS=0` — several `ALTER … MODIFY/DROP` a column
+that participates in a foreign key and otherwise fail with error 1832. (The blank dump sets this in
+its own header.)
+
 ## Adding a new change (the rules)
 
 1. Pick the right folder for the target DB: `Core/`, `Logs/`, the shared `Client/` (every

package/knowledge/2.0/apps/dbchanges2/workflows/client-onboarding.md

@@ -0,0 +1,97 @@
+---
+title: 2.0 New-Client Onboarding (manual process)
+framework: "2.0"
+repo: dbchanges2
+project: Database Changes
+client: shared
+type: workflow
+status: active
+updated: 2026-06-23
+owners: ["mhammontree"]
+files:
+  - Client/
+  - Client_<Tenant>/
+  - Core/
+  - Logs_Client/
+related:
+  - ../architecture.md
+  - ../../../1.0/apps/test/features/toga2-client-onboarding-sql.md
+  - ../../api2/features/tickets-api.md
+---
+
+## Summary
+
+How to manually stand up a new 2.0 client (tenant). A tenant spans three databases on three
+clusters — `Client_<Name>` (client cluster), `Logs_<Name>` (logs cluster), `Archive_<Name>`
+(archive cluster) — plus registration rows in **Core** and two API keys. The schema + baseline
+data come from the dbchanges2 **blank**; the Core/client registration + API keys are generated by
+the [onboarding SQL generator](../../../1.0/apps/test/features/toga2-client-onboarding-sql.md).
+Goal: every `Client_<Name>` DB is architecturally identical.
+
+## Steps
+
+Order matters — each step assumes the prior one ran.
+
+1. **Decide identifiers** — formal name, identifier (PascalCase → `Client_<Id>`), subdomain
+   (lowercase), email domain(s) with TLD, and any modules.
+2. **Create the three databases** — `CREATE DATABASE Client_<Id>` (client cluster),
+   `Logs_<Id>` (logs cluster), `Archive_<Id>` (archive cluster). `Archive_<Id>` can be empty.
+3. **Build `Client_<Id>` schema + baseline** — apply the current blank
+   (`Client/<DATE>-BLANK_CLIENT_DATABASE.sql` — latest-dated), which creates all tables **and** the
+   baseline seed (roles, full ACL, reference/lookup tables, UI config). Run with
+   `SET FOREIGN_KEY_CHECKS=0` (the loose schema files assume it; see Gotchas).
+4. **Build `Logs_<Id>`** — apply `Logs_Client/<DATE>_BLANK_CLIENT_LOGS_DATABASE.SQL`. The API logs
+   here and checks the auth-rate limit against it, so it **must** exist for the API to work.
+5. **Generate the inserts** — run `test/team/generate_toga2_onboarding_sql.php` (set the client
+   consts). It emits Core inserts + the two API-key inserts.
+6. **Run Core inserts on the core cluster** — `Core.Databases`, `Core.Clients`, `Core.Domains`
+   (every app × env), `Core.ClientEmailDomains`, `Core.DatabaseHosts`. This is what makes the API
+   route to the tenant.
+7. **Run the API-key inserts on the client cluster** (against `Client_<Id>`) — two `Apis` rows
+   (internal "Agilant" + the client key) and their `Apis_Roles` links to `Base`+`API`. Distribute
+   the secrets out-of-band (internal → our systems; client → the client). **Never commit secrets.**
+8. **Register for shared changes** — append `Client_<Id>` to `test/team/2.0 deployment/Clients_Db.txt`
+   so future shared `Client/` changes fan out to it.
+9. **Configure client reference/ACL data** — seed the client's ticket reference data
+   (Urgencies, TicketTypes, TicketStages, TicketTopics) and any record/field ACL beyond baseline.
+10. **Verify** — authenticate via the API with `{client = Core.Clients.uuid, api = Apis.uuid,
+    secret = Apis.secret}`, then a smoke request (e.g. create a ticket).
+
+## Systems involved
+
+- **dbchanges2** — the blank (schema + baseline seed), loose `Client/` changes, `Logs_Client/`
+  blank, and the generated `Core/` + `Client_<Name>/` onboarding SQL.
+- **test** (1.0) — `generate_toga2_onboarding_sql.php` produces the Core + API-key inserts.
+- **Core DB** — `Clients`, `Databases`, `DatabaseHosts`, `Domains`, `ClientEmailDomains`
+  (route/identity metadata; supplies the `client` uuid used at auth).
+- **api2 / _underscore** — the API the client calls; verify here.
+- **Bastion** — production deploy path (upload SQL, source per cluster).
+
+## Edge cases & escalation
+
+- **Logs/Archive scope** — building the `Logs_`/`Archive_` *schemas* is sometimes treated as a
+  later phase, but `Logs_<Id>` is required for the API to authenticate/log. Their **Core
+  registration** rows (Databases/DatabaseHosts) are always generated regardless.
+- **Reference data** — a fresh client has roles/ACL/lookups from the blank, but **not** ticket
+  reference data (Urgencies/TicketTypes/TicketStages/TicketTopics). Until seeded, ticket creates
+  that reference them return `EV-12`.
+- **Drift before consolidation** — loose `Client/` files must already be applied to all existing
+  clients before they're consolidated/archived (otherwise the new blank diverges from live
+  clients). See the dbchanges2 architecture doc.
+
+## Gotchas
+
+- **`FOREIGN_KEY_CHECKS=0`** is required when applying the loose schema files — several
+  `ALTER … MODIFY/DROP` a column that's in an FK and fail with error 1832 otherwise.
+- **`Apis` rows are in the CLIENT database**, not Core. Core only holds `Clients`/`ClientEmailDomains`
+  /`ClientApiIdentities`. Auth needs three values: `client` = `Core.Clients.uuid`, `api` =
+  `Client_<Id>.Apis.uuid`, `secret` = `Client_<Id>.Apis.secret`.
+- **`Apis_Roles` needs `Base`+`API` to pre-exist** in `Client_<Id>` — they come from the blank
+  seed. If the blank lacks roles, the role links insert zero rows and the key can't authorize.
+- **Never commit secrets** — the generated `Apis` secrets go in a non-committed artifact; the Core
+  inserts are secret-free and committable.
+- **Domain URLs** — dev uses `http://<sub>.togaX` (no TLD); beta/prod use `https://…<env>.togaX.com`.
+
+## Change history
+
+- 2026-06-23 — Initial capture from the Fordham onboarding (TRUE-79702). (mhammontree)

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

@@ -3,6 +3,7 @@
 | Doc | Summary | Files |
 |-----|---------|-------|
 | [Worker (worker2) Architecture](architecture.md) | Worker (repo `worker2`) is an AWS Elastic Beanstalk **Worker Tier** application that processes background jobs. | worker2/Controller/Index.php, worker2/Worker/, worker2/LambdaFunctions/, _underscore/Worker.php |
+| [ClickUp Connectivity Watchdog](features/clickup-connectivity-watchdog.md) | A cron watchdog that emails when the ClickUp integration looks disconnected during business hours. | worker2/Worker/Clickup/Health.php, worker2/Database/ClickupHealthWatchdog.sql |
 | [ClickUp Project & Opportunity Multi-List Routing](features/clickup-project-routing.md) | Routes ClickUp tasks into the correct **secondary multi-list memberships** based on their custom-field values, via the `clickup` webhook. | worker2/Worker/Clickup/Project.php, worker2/Worker/Clickup.php |
 | [ClickUp Work Type Automation (Committed / Conditional / Stretch)](features/clickup-work-type-automation.md) | The ClickUp webhook handler (`_Worker_Clickup`) automatically maintains each task's **Work Type** custom field — `Committed`, `Conditional`, or `Stretch` — base | worker2/Worker/Clickup.php, worker2/Tests/Worker/ClickupWorkTypeTest.php |
 | [Creating Worker Actions](features/creating-worker-actions.md) | How to add a new callable Worker action — a PHP class whose `public static` methods are invoked as background jobs (via webhook, cron, or `_Worker::runTask()`). | worker2/Worker/, worker2/Controller/Index.php, _underscore/Worker.php |

package/knowledge/2.0/apps/worker2/features/clickup-connectivity-watchdog.md

@@ -0,0 +1,81 @@
+---
+title: ClickUp Connectivity Watchdog
+framework: "2.0"
+repo: worker2
+project: Worker
+client: shared
+type: feature
+status: active
+updated: 2026-06-23
+owners: [ajean]
+files:
+  - worker2/Worker/Clickup/Health.php
+  - worker2/Database/ClickupHealthWatchdog.sql
+related:
+  - ./clickup-project-routing.md
+  - ../architecture.md
+---
+
+## Summary
+
+A cron watchdog that emails when the ClickUp integration looks disconnected during business
+hours. Implemented in `_Worker_Clickup_Health` (action `Clickup/Health/Check`). It exists
+because the ClickUp webhook subscriptions can silently die (a dropped subscription, a ClickUp
+outage, or our endpoint failing), and nobody notices until reporting/automations drift.
+
+## Key files / entry points
+
+- `worker2/Worker/Clickup/Health.php` — `_Worker_Clickup_Health::Check(): string` (the cron
+  action) + `initialize()` (registers the `Team` DB, same pattern as `_Worker_Team_Transcripts`).
+- `worker2/Database/ClickupHealthWatchdog.sql` — run-once reference: the `Team.ClickUpHealthState`
+  table + the `Core.CronJobs` row. Canonical migrations live in `dbchanges2`
+  (`Team/2026-06-23a …`, `Core/2026-06-23a …`).
+
+## How it works
+
+Scheduled every 15 min on weekdays 09:00–16:45 Central (cron `0,15,30,45 9-16 * * 1-5`).
+`Check()` evaluates two signals and emails `ajean@togatech.com` if either fires:
+
+1. **Inbound silence** — `MAX(dtCreated)` of `Core.WorkerJobs WHERE action = 'Clickup/Webhook'`
+   (exact match, so the watchdog's own `Clickup/Health/Check` rows don't count). Elapsed minutes
+   are computed by **MySQL `TIMESTAMPDIFF`** (no PHP/DB timezone mismatch). Alerts when ≥ 60 min
+   silent, but only from the **second business hour onward** (a one-hour warm-up so the expected
+   overnight gap isn't flagged at 09:00).
+2. **Webhook health** — `GET /team/{id}/webhook`; any subscription whose endpoint contains
+   `togahub.com` with `health->status == 'failing'`. The probe is wrapped in try/catch — if the
+   probe call itself throws, that is treated as a connectivity signal too.
+
+De-duplication: `Team.ClickUpHealthState` (single row) records `dtLastAlerted`; an ongoing
+outage re-emails at most once per 60 min (`shouldAlert`), and the flag is cleared when ClickUp
+is healthy again (`clearAlert`) so each fresh outage notifies once.
+
+## Data model
+
+- **`Team.ClickUpHealthState`** — single-row alert state: `id`, `uuid`, `dtCreated`, `dtUpdated`,
+  `dtLastAlerted` (NULL when healthy), `lastReason`. The row is created lazily on first alert.
+- **`Core.CronJobs`** — one row, action `Clickup/Health/Check`, `maxExecutionTime` 120.
+
+## Client variations
+
+None — internal monitoring for Agilant's ClickUp workspace.
+
+## Gotchas / known issues
+
+- **Detects ClickUp-side problems only.** It runs *inside* the worker/cron pipeline, so it
+  assumes that pipeline is healthy. It will **not** fire if the EB worker tier, the CronScheduler
+  Lambda, or the database is itself down — full worker-down detection needs an external uptime
+  monitor (not built).
+- **The inbound query must match `Clickup/Webhook` exactly.** A `LIKE 'Clickup/%'` would also
+  match the watchdog's own `Clickup/Health/Check` rows and the timer would never expire.
+- **Email identifier is `'True'`** (the internal/team `clientIdentifier`, consistent with other
+  team alerts via `_Worker_Notification_Email::Send`).
+- **Business window is enforced in code too** (Mon–Fri, 09:00–17:00 Central), not just in the
+  cron schedule, so a manual run outside hours is a safe no-op.
+
+## Change history
+- 2026-06-23 — Created. Watchdog cron emails on 60-min inbound webhook silence or a failing subscription during business hours; deduped via `Team.ClickUpHealthState`. (ajean)
+
+## Related docs
+
+- [ClickUp Project & Opportunity Multi-List Routing](./clickup-project-routing.md) — the integration this watches.
+- [Worker (worker2) Architecture](../architecture.md) — CronJobs, WorkerJobs, always-HTTP-200.

package/knowledge/2.0/apps/worker2/features/clickup-project-routing.md

@@ -6,21 +6,23 @@ project: Worker
 client: shared
 type: feature
 status: active
-updated: 2026-06-09
-owners: [jcardinal]
+updated: 2026-06-23
+owners: [jcardinal, ajean]
 files:
   - worker2/Worker/Clickup/Project.php
   - worker2/Worker/Clickup.php
 related:
   - ../architecture.md
   - ./creating-worker-actions.md
+  - ./clickup-connectivity-watchdog.md
 ---
 
 ## Summary
 
 Routes ClickUp tasks into the correct **secondary multi-list memberships** based on their
 custom-field values, via the `clickup` webhook. Implemented in `_Worker_Clickup_Project`
-(an abstract worker class) with three independent entry points covering three ClickUp spaces.
+(an abstract worker class) with three independent routing entry points covering three ClickUp
+spaces, plus a **hub-placement guard** that keeps Epics/Opportunities anchored to their hub.
 
 **Hybrid design (the central constraint):** ClickUp's public **v2 API forbids changing or
 removing a task's home list** (`400 TASK_035 — Task home list cannot be altered`). So:
@@ -35,8 +37,9 @@ removing a task's home list** (`400 TASK_035 — Task home list cannot be altere
 - `worker2/Worker/Clickup.php` — delegates from `_Worker_Clickup::Webhook()`:
   - `taskStatusUpdated` (~L643): calls `handleEpicUpdate($taskId)` unconditionally.
   - `taskUpdated` (~L826–828): behind a **self-trigger guard**, calls all three handlers.
+  - `taskCreated` and `taskMoved`: call `enforceHubPlacement($taskId)` (the guard, below).
 
-Three public entry points (all `public static function …(string $taskId): void`):
+Three routing entry points (all `public static function …(string $taskId): void`):
 
 | Handler | Space (guard) | Driver fields | Effect |
 |---|---|---|---|
@@ -44,13 +47,39 @@ Three public entry points (all `public static function …(string $taskId): void
 | `handleOpportunityUpdate` | Opportunity/RFP Hub `90113928591` | Business Unit, Project Category, Opportunity Stage | Adds to the LS folder's **Opportunities** list when BU = "Lifecycle Services", category maps to an LS folder, and stage is not `Closed Lost` / not Won/Signed; removes otherwise. |
 | `handleAmOpportunityUpdate` | Opportunity/RFP Hub `90113928591` | Business Unit, Project Category, Opportunity Stage, Project Phase | Two passes: (1) space-level A&M Opportunities list; (2) A&M folder list driven by Opportunity Stage, with Execution→Completion driven by Project Phase = "Complete". |
 
+### Hub-placement guard — `enforceHubPlacement(string $taskId): void` (added 2026-06-23)
+
+Keeps **Epics in Project Hub** and **Opportunities in Opportunity/RFP Hub**. Called from the
+`taskCreated` and `taskMoved` cases in `Worker/Clickup.php`. Unlike the three routing handlers
+(which identify tasks structurally), it identifies the type by **custom Task Type**
+(`custom_item_id`, configured via the `TASK_TYPE_EPIC_ID` / `TASK_TYPE_OPPORTUNITY_ID`
+constants). A task is **misplaced** when its **home** `space->id` is not its hub — i.e. it was
+created in, or moved into, Lifecycle Services / Advisory & Modernization (or any other space).
+
+For a misplaced top-level task it:
+1. **Backfills metadata** (best-effort, LS/A&M only) — Business Unit from the home space
+   (`getBusinessUnitForSpaceId()`), Project Category from the home folder
+   (`getProjectCategoryForFolderId()`, the **inverse** of `getLsFolderKey`/`getAmFolderKey` —
+   keep them in sync). Written via `setDropdownFieldByName()`, which handles both `drop_down`
+   and `labels` field shapes and writes only when the value differs.
+2. **Re-adds the correct hub intake list** as a secondary membership (Epic →
+   `PROJECT_HUB_INTAKE_LIST_ID`, Opportunity → `OPPORTUNITY_HUB_INTAKE_LIST_ID`). The home list
+   itself cannot be moved by the API (TASK_035) — a human must do that.
+3. **Posts a one-time comment** (only when it actually just added the membership) telling the
+   user to move the home list back manually.
+
+**Ships inert**: with `TASK_TYPE_*_ID` both `null` it is a no-op, so it can deploy before the
+ids are discovered. Configure via the `DiscoverTaskTypes()` / `DiscoverIds()` actions, then
+`RegisterHubGuardWebhooks()`.
+
 ## How it works
 
 1. The `clickup` webhook → `_Worker_Clickup::Webhook()` → delegation in `Worker/Clickup.php`.
 2. Each handler fetches task details via `_Worker_Clickup::getTaskDetails()` (a per-invocation
    `static` cache shared across all handlers in one job), then guards on **space id** and
-   **top-level** (`parent` empty). Epics/tasks are identified structurally — ClickUp Task
-   Types is not enabled, so `task_type` is unreliable.
+   **top-level** (`parent` empty). The three routing handlers identify Epics/tasks
+   **structurally** (space + top-level). Custom **Task Types are now configured**, and the
+   newer `enforceHubPlacement` guard keys on `custom_item_id` to recognize Epics/Opportunities.
 3. Custom fields are read by name via `extractCustomFields()` (one pass, last-non-null-wins,
    trimmed) → mapped to a target list id → reconciled by `applyMultiListPlacement()`:
    POST the target if absent, DELETE every other in-scope list (DELETE failures are caught
@@ -80,8 +109,9 @@ None in MySQL — all state lives in ClickUp. Each invocation is recorded as a n
 
 ClickUp structure encoded as constants in `Project.php`: 4 LS folders
 (Onsite, Factory, Audio-Visual, Managed Services), 4 A&M folders (Retainer, Security,
-AI & Data Center, Cloud), plus space-level lists. Regenerate with the `DiscoverIds()` /
-`DiscoverAmIds()` diagnostic actions if the ClickUp structure changes.
+AI & Data Center, Cloud), plus space-level lists, the hub intake lists, and the Epic/Opportunity
+custom Task Type ids. Regenerate with the `DiscoverIds()` / `DiscoverAmIds()` /
+`DiscoverTaskTypes()` diagnostic actions if the ClickUp structure changes.
 
 ## Client variations
 
@@ -89,38 +119,52 @@ None — uniform across all clients (shared internal automation for Agilant's Cl
 
 ## Gotchas / known issues
 
+- **Hub-guard correctness rests on the HOME space:** `enforceHubPlacement` filters on
+  `taskDetails->space->id`, which always follows the task's **home** list. A hub Epic that the
+  routing handlers mirror into LS/A&M as a *secondary* membership still reports its home hub as
+  the space, so the guard correctly ignores it. Filtering on home space is what stops the guard
+  from fighting the secondary-membership routing.
+- **`getProjectCategoryForFolderId()` must stay in sync** with `getLsFolderKey`/`getAmFolderKey`
+  and the `*_FOLDER_*` constants — it is their inverse (folder id → Project Category value).
 - **List-name slash spacing differs by space, intentionally:** LS uses
   `"Client Scoping / Discovery"` (space before slash); A&M uses `"Client Scoping/ Discovery"`
   (no space). These match the real ClickUp list names — do not "fix" one to match the other.
 - **String-typed list IDs:** `collectCurrentMemberships()` returns IDs as **strings** and
   avoids array-key dedup, because PHP coerces numeric-string keys to int and would break the
-  strict `in_array` comparisons against the string constants.
-- **Shared `getTaskDetails()` cache is stale after writes:** all three handlers share one
-  cached task fetch per job. After one handler mutates memberships, the cached `locations`
-  are stale for the others. Currently safe only because the space guards are mutually
-  exclusive (a task lives in one space → exactly one handler does work). Wiring a second
-  handler onto `taskStatusUpdated`, or overlapping list scopes, would break this.
-- **`RATE_LIMIT_DELAY_US` (120ms) is defined but unused** — pacing relies entirely on
-  `_Component_Api_Clickup::send()`'s internal `sleep(1)`. `handleAmOpportunityUpdate` can
-  issue several placement passes (multiple POST/DELETE) per event.
+  strict `in_array` comparisons against the string constants. (`getProjectCategoryForFolderId`
+  relies on that same numeric-string→int coercion being *consistent* between map keys and the
+  lookup, so it is correct; a hidden/leading-zero folder id falls through to `null`.)
+- **Shared `getTaskDetails()` cache is stale after writes:** all handlers share one cached task
+  fetch per job. After one handler mutates memberships, the cached `locations` are stale for the
+  others. Safe today because the space guards are mutually exclusive (a task lives in one space →
+  exactly one handler does work).
+- **`RATE_LIMIT_DELAY_US` (120ms):** now used by `enforceHubPlacement` / `setDropdownFieldByName`
+  (`usleep`); the three routing handlers still rely on `_Component_Api_Clickup::send()`'s internal
+  `sleep(1)`.
 - **POST failures are fatal, DELETE failures are tolerated** — a failed ADD leaves the task
   out of its correct list (surfaced as job failure); a failed DELETE (most likely TASK_035,
   which shouldn't occur on secondary lists) is logged with `[ClickupProject]` and skipped.
-- **Webhook subscriptions** must cover each space. Three exist, all → `webhook.togahub.com/clickup`:
+- **Webhook subscriptions** must cover each space, all → `webhook.togahub.com/clickup`. Routing:
   legacy sprint space `90020178491`, Project Hub `90113939341`, Lifecycle Services
-  `90114156087`. Opportunity Hub coverage is registered via `RegisterOpportunityWebhook()`.
+  `90114156087`; Opportunity Hub via `RegisterOpportunityWebhook()`. The hub guard additionally
+  needs **`taskCreated` on LS + A&M** and a **workspace-wide `taskMoved`**, registered via
+  `RegisterHubGuardWebhooks()` (which skips any already covered to avoid double-delivery).
 
 ## Diagnostics
 
-Read-only actions (no writes), invoked via `curl -X POST https://worker.togahub.com/` with
+Read-only / setup actions, invoked via `curl -X POST https://worker.togahub.com/` with
 `{"action":"Clickup/Project/<Method>","parameters":{...}}`:
-`DiagnoseOpportunity`, `DiagnoseAmTask` (routing verdicts), `DiscoverIds`, `DiscoverAmIds`
-(print constant declarations), `RegisterOpportunityWebhook` (one-time setup).
+`DiagnoseOpportunity`, `DiagnoseAmTask` (routing verdicts), `DiscoverIds`, `DiscoverAmIds`,
+`DiscoverTaskTypes` (print constant declarations / custom-task-type ids),
+`TestHubGuardMappings` (pure self-test of the folder→category & space→BU maps; expect
+`RESULT: PASS`), `RegisterOpportunityWebhook` and `RegisterHubGuardWebhooks` (one-time setup).
 
 ## Change history
+- 2026-06-23 — Added the hub-placement guard (`enforceHubPlacement` on `taskCreated`/`taskMoved`): re-anchors misplaced Epics/Opportunities to their hub by custom Task Type + home space, backfills Business Unit/Project Category, and notifies. Added `DiscoverTaskTypes`, `RegisterHubGuardWebhooks`, `TestHubGuardMappings`. Corrected the earlier "Task Types not enabled" note. (ajean)
 - 2026-06-09 — Documented ClickUp secondary multi-list routing (hybrid native-automation + worker design, three space handlers, self-trigger guard). (jcardinal)
 
 ## Related docs
 
 - [Worker (worker2) Architecture](../architecture.md) — always-HTTP-200, commit-before-SQS.
 - [Creating Worker Actions](./creating-worker-actions.md) — the worker-action contract.
+- [ClickUp Connectivity Watchdog](./clickup-connectivity-watchdog.md) — the email-alert health check.

package/knowledge/INDEX.md

@@ -16,9 +16,9 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 ## 2.0 framework
 
 - **_underscore** (_Underscore) _(framework core)_ — 11 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
-- **worker2** (Worker) — 10 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
-- **api2** (API) — 4 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)
+- **worker2** (Worker) — 11 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
+- **api2** (API) — 5 doc(s) → [2.0/apps/api2/INDEX.md](2.0/apps/api2/INDEX.md)
+- **dbchanges2** (Database Changes) _(framework core)_ — 2 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) — 2 doc(s) → [2.0/apps/saml/INDEX.md](2.0/apps/saml/INDEX.md)
 - **toga2-view** (TOGa View Frontend) — 1 doc(s) → [2.0/apps/toga2-view/INDEX.md](2.0/apps/toga2-view/INDEX.md)
@@ -41,6 +41,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 - **Compass Canada** (`compass-canada`) → [clients/compass-canada/INDEX.md](clients/compass-canada/INDEX.md)
 - **Compass USA** (`compass-usa`) → [clients/compass-usa/INDEX.md](clients/compass-usa/INDEX.md)
 - **Elite** (`elite`) → [clients/elite/INDEX.md](clients/elite/INDEX.md)
+- **Fordham University** (`fordham`) → [clients/fordham/INDEX.md](clients/fordham/INDEX.md)
 - **GroWrk** (`growrk`) → [clients/growrk/INDEX.md](clients/growrk/INDEX.md)
 - **New York City Department of Education** (`nycdoe`) → [clients/nycdoe/INDEX.md](clients/nycdoe/INDEX.md)
 - **NYC Health & Hospitals** (`nychh`) → [clients/nychh/INDEX.md](clients/nychh/INDEX.md)

package/knowledge/clients/fordham/INDEX.md

@@ -0,0 +1,5 @@
+# Client: Fordham University `fordham`
+
+| Doc | Framework | Summary | Files |
+|-----|-----------|---------|-------|
+| [Fordham University](profile.md) | 2.0 | Fordham University (`fordham.edu`), `clientIdentifier` **Fordham**, onboarded onto the 2.0 platform in June 2026 (TRUE-79702). |  |

package/knowledge/clients/fordham/profile.md

@@ -0,0 +1,49 @@
+---
+title: "Fordham University"
+framework: "2.0"
+apps:
+  - _underscore
+  - api2
+  - dbchanges2
+project: API
+client: fordham
+type: profile
+status: active
+updated: 2026-06-23
+owners: ["mhammontree"]
+files: []
+related:
+  - ../../2.0/apps/api2/features/tickets-api.md
+  - ../../2.0/apps/dbchanges2/workflows/client-onboarding.md
+---
+
+## Summary
+
+Fordham University (`fordham.edu`), `clientIdentifier` **Fordham**, onboarded onto the 2.0 platform
+in June 2026 (TRUE-79702). Their integration uses the **TOGa 2.0 ticket API** (`/v2/tickets`) — they
+create/update/read support tickets in our system via REST. Tickets are the **generic** flow (not
+entitlement-based like PC Matic): the request body is ticket fields at the top level.
+
+## Onboarding
+
+Provisioned via the standard [2.0 client onboarding process](../../2.0/apps/dbchanges2/workflows/client-onboarding.md):
+`Client_Fordham` / `Logs_Fordham` / `Archive_Fordham`, Core registration, and two API keys
+(internal "Agilant" + the "Fordham" client key). The committed dbchanges2 artifacts are
+`Client/<DATE>-BLANK_CLIENT_DATABASE.sql` (seeded blank) and `Core/<DATE>-onboard_Fordham.sql`
+(Core inserts); the API-key inserts (with secrets) are kept out of the repo.
+
+## Integration / API
+
+- Uses **generic `/v2/tickets`** (POST/PUT/GET) — see [tickets-api](../../2.0/apps/api2/features/tickets-api.md).
+- Customer-facing docs delivered (TRUE-79699): a Markdown guide + a Postman collection in PC-Matic
+  style (globals for `{{url}}`/`{{accessToken}}`, hardcoded creds in the auth body).
+
+## Known gaps
+
+- **Ticket reference data not yet seeded** — `Urgencies`, `TicketTypes`, `TicketStages`,
+  `TicketTopics` are empty for Fordham, so ticket creates can only set descriptions/notes until those
+  are configured; referencing them returns `EV-12`.
+
+## Change history
+
+- 2026-06-23 — Initial onboarding + ticket API integration. (mhammontree)

package/package.json

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