toga-ai 1.0.776 → 1.0.778

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

@@ -9,6 +9,7 @@
 | [Create Elastic Beanstalk Environment (script)](features/create-elastic-beanstalk.md) | `team/aws/create_elastic_beanstalk.php` is a **standalone** (no `App_` framework) constants-driven PHP generator. | test/team/aws/create_elastic_beanstalk.php |
 | [Developer Generators (password, UUID)](features/dev-generators.md) | Two tiny **1.0 `App_` framework** convenience scripts for everyday developer needs. | test/team/generate_password.php, test/team/uuid.php |
 | [Forecast vs NetSuite Discrepancy Analysis](features/forecast-netsuite-discrepancy-analysis.md) | `team/forecast-netsuite/discrepancy_analysis.php` detects discrepancies between our **Forecast database** and **NetSuite** (the source of truth for all sales da | test/team/forecast-netsuite/discrepancy_analysis.php |
+| [GitHub Audit Script (team/github_audit.php)](features/github-audit-script.md) | `team/github_audit.php` is a **standalone** (no `App_` framework) browser/CLI script that reports lines added/removed, commits, unique authors, and active repos | test/team/github_audit.php |
 | [@goagilant.com → @togatech.com Email-Domain Migration (1.0 + 2.0)](features/goagilant-to-togatech-email-migration.md) | Reference + technique for migrating the company email domain `@goagilant.com` → `@togatech.com` across **both** platforms. | migrate_goagilant_to_togatech_2026-06-26.sql, migrate_goagilant_to_togatech_LEGACY_2026-06-26.sql |
 | [Static (no-DB) Regression Harness for 1.0 Logic + Source Drift Guard](features/static-no-db-regression-harness.md) | 1.0 has **no PHPUnit**, and most of its business logic sits inside methods that also write SQL, so "just call it" means standing up a client database. | test/@Mark/AIG/test_multi_email.php, test/@Mark/TRUE-80952/test_queued_email_attachments.php, library/app/database.php, library/app/api/toga2.php |
 | [TableView Builder (2.0 TableViews SQL generator)](features/tableview-builder.md) | `team/tableViewBuilder/` generates SQL `INSERT` statements for the **2.0 `TableViews`**, `TableViewFields`, and `TableViewJoins` tables from a plain SQL `SELECT | test/team/tableViewBuilder/TableViewGenerator.php, test/team/tableViewBuilder/index.php, test/team/tableViewBuilder/Instructions.md |

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

@@ -22,6 +22,7 @@ related:
   - ./features/dev-generators.md
   - ./features/talos-kb-pipeline.md
   - ./features/goagilant-to-togatech-email-migration.md
+  - ./features/github-audit-script.md
 ---
 
 ## Summary
@@ -85,6 +86,7 @@ manually against the target database; they do not execute changes themselves.
 | `generate_password.php`, `uuid.php` | 1.0 | dev utility | [dev-generators](./features/dev-generators.md) |
 | `talos/kb_uploader.php`, `talos/kb_processor.php` | standalone | S3 + AWS Bedrock KBs | [talos-kb-pipeline](./features/talos-kb-pipeline.md) |
 | `migrate_goagilant_to_togatech_*.sql` | standalone | 2.0 `Client_` DBs + 1.0 schemas | [goagilant-to-togatech-email-migration](./features/goagilant-to-togatech-email-migration.md) |
+| `github_audit.php` | standalone | GitHub org (agilantsolutions) | [github-audit-script](./features/github-audit-script.md) |
 
 **Retired / not documented:** `team/DOA_gitbook/` is being retired.
 
@@ -95,3 +97,6 @@ manually against the target database; they do not execute changes themselves.
   processor in [talos-kb-pipeline](./features/talos-kb-pipeline.md).
 - 2026-06-26 — Documented the @goagilant.com → @togatech.com email-domain migration SQL
   artifacts in [goagilant-to-togatech-email-migration](./features/goagilant-to-togatech-email-migration.md).
+- 2026-09-04 — Documented `team/github_audit.php`, the standalone monthly GitHub org
+  code-churn audit (later ported into Tools) in
+  [github-audit-script](./features/github-audit-script.md).

package/knowledge/1.0/apps/test/features/github-audit-script.md

@@ -0,0 +1,60 @@
+---
+title: GitHub Audit Script (team/github_audit.php)
+framework: "1.0"
+repo: test
+project: Test
+client: shared
+type: feature
+status: active
+updated: 2026-09-04
+owners: [jcardinal]
+files:
+  - test/team/github_audit.php
+related:
+  - ../architecture.md
+  - ../../tools/features/github-audit.md
+---
+
+## Summary
+
+`team/github_audit.php` is a **standalone** (no `App_` framework) browser/CLI script that
+reports lines added/removed, commits, unique authors, and active repos across the
+`agilantsolutions` GitHub org for one calendar month. Quick, run-it-locally monthly audit.
+
+This is the **original build** that was then ported into the Tools app as
+[`/developers/github-audit`](../../tools/features/github-audit.md). The app version is the
+maintained one; this script is the lightweight local runner.
+
+## How it works
+
+1. **Config** via `const` at the top of the file: `AUDIT_MONTH` (`YYYY-MM`) and
+   `GITHUB_ORG`.
+2. **Token** is read from the `GITHUB_AUDIT_TOKEN` **environment variable** — never
+   hardcoded, so it can't be committed.
+3. Same **per-commit exact counting** as the app tool: list each commit in the month window,
+   fetch each commit's stats, skip merge commits and forks.
+4. Same **reliability**: `202` "stats not ready" retry, secondary rate-limit retry, and a
+   primary rate-limit floor that stops the run.
+5. Same **month-range validation** (`^\d{4}-\d{2}$` plus month number 01–12, so `2026-99`
+   is rejected rather than silently overflowed by `DateTime`).
+
+Fits the `test` repo's documented **`team/` scripts** surface (see architecture).
+
+## Gotchas
+
+- **Token must be in the environment.** With `GITHUB_AUDIT_TOKEN` unset the run fails — set
+  it before running; do not paste a PAT into the file.
+- **Shared org rate limit.** A big audit consumes the org's GitHub budget; avoid running it
+  in parallel with the Tools GitHub Audit or the Design tool (same org token pool).
+
+## Change history
+
+- 2026-09-04 — Created. Standalone monthly org code-churn audit script; token from
+  `GITHUB_AUDIT_TOKEN`. Later ported into the Tools app as `/developers/github-audit`.
+  (jcardinal)
+
+## Related docs
+
+- [Test Architecture](../architecture.md)
+- [Tools GitHub Audit (app port)](../../tools/features/github-audit.md)
+</content>

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

@@ -6,12 +6,13 @@
 | [/clickup/aliases — ClickUp Label-Alias Admin (Tools → 2.0 Team schema)](features/clickup-label-aliases-admin.md) | The human side of the NetSuite→ClickUp **Stakeholders / End Customer** labels. | tools/mvc/clickup/aliases/get.php, tools/mvc/clickup/aliases/post.php, tools/_/app/clickup/aliases.php, tools/_/app/nav.php |
 | [Developer Dashboard (ClickUp Sprint, tools /developer)](features/clickup-sprint-dashboard.md) | A native **ClickUp sprint dashboard** in the 1.0 `tools` app at route `/developer` (the **"Developer Dashboard"**, renamed from `/clickup/react` / "Clickup" — s | tools/_/app/clickup/sprint.php, tools/v2/sprints/tile/index.php, tools/v2/sprints/current/index.php, tools/v2/sprints/status-breakdown/index.php, tools/v2/sprints/worktype-breakdown/index.php, tools/v2/sprints/points-by-dev/index.php, tools/v2/sprints/burndown/index.php, tools/assets/clickup/sprint-dashboard.html, tools/mvc/developer/get.php, tools/mvc/login/get.php, tools/_/app/nav.php |
 | [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 |
-| [Compass User & Persona Admin (tools /compass/users, /compass/personas)](features/compass-user-persona-admin.md) | Two pages in the Tools `developers` nav folder that let staff do, in a browser, the two Compass requests that used to mean "email a developer, who writes a `dbc | tools/_/app/compass.php, tools/mvc/compass/users/get.php, tools/mvc/compass/users/post.php, tools/mvc/compass/personas/get.php, tools/mvc/compass/personas/post.php, tools/_/app/nav.php, tools/config.production.ini |
+| [Compass User & Persona Admin (tools /compass/users, /compass/personas)](features/compass-user-persona-admin.md) | Two pages in the Tools `developers` nav folder that let staff do, in a browser, the Compass requests that used to mean "email a developer, who writes a `dbchang | tools/_/app/compass.php, tools/mvc/compass/users/get.php, tools/mvc/compass/users/post.php, tools/mvc/compass/personas/get.php, tools/mvc/compass/personas/post.php, tools/_/app/nav.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/developers/password/post.php |
 | [/errors Curation Console (Tools → shared Core Logs DB)](features/errors-curation-console.md) | Internal-only triage/curation screen for the 2.0 Issue/Event error-reporting pipeline, built as a 1.0 Tools MVC page reading the **shared Core Logs DB** through | tools/mvc/errors/get.php, tools/mvc/errors/post.php, tools/mvc/errors/issue/get.php, tools/assets/css/style.css, tools/_/app/nav.php, tools/config.production.ini |
+| [GitHub Audit (monthly code-churn report)](features/github-audit.md) | An internal report at **`/developers/github-audit`** (Developers nav group, personas `['Development Team','TOGa Technology']`) that shows, for one calendar mont | tools/_/app/github/audit.php, tools/mvc/developers/github-audit/get.php, tools/mvc/developers/github-audit/post.php, tools/_/app/nav.php |
 | [Legacy Email Notifier (tools /email-migration/notify)](features/legacy-email-notifier.md) | An SSO-gated admin tool at **`/email-migration/notify`** (nav group **Email Migration** > **Legacy Notifier**, personas `['TOGa Technology','Development Team']` | tools/mvc/email-migration/notify/get.php, tools/mvc/email-migration/notify/post.php, tools/_/app/nav.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, library/app/error.php, library/app/database.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, library/app/error.php, library/app/database.php, library/app/string.php |
 | [OneUptime Monitor Status Panel & Outage Alerting (tools /developer)](features/oneuptime-monitor-status-panel.md) | A live **operational monitor column** on the wall-display dashboard at `/developer` (the route was renamed from `/clickup/react` — the internal asset path `asse | tools/assets/clickup/sprint-dashboard.html, tools/_/app/clickup/monitors.php, tools/v2/monitors/status/index.php, tools/mvc/developer/get.php |
 | [Tools Persona-Gated Navigation (App_Nav)](features/persona-gated-navigation.md) | `App_Nav` is the Tools app's two-level, **persona-gated** navigation. | tools/_/app/nav.php, tools/mvc/get.php |
 | [Tools SAML SSO Consumer & Persona-Gated Auth (App_Auth)](features/saml-sso-auth.md) | `App_Auth` is the Tools app's authentication layer: it consumes the SAML gateway `?saml=` handoff (see the 2.0 SAML downstream integration contract), establishe | tools/_/app/auth.php, tools/mvc/sso/initiate/get.php, tools/mvc/sso/get.php, tools/mvc/login/get.php, tools/mvc/login/post.php, tools/mvc/logout/get.php, tools/mvc/get.php, tools/config.production.ini, tools/config.local.ini |

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

@@ -32,6 +32,7 @@ related:
   - ./features/persona-gated-navigation.md
   - ./features/developer-tools.md
   - ./features/oneuptime-monitor-status-panel.md
+  - ./features/github-audit.md
   - ../library/architecture.md
   - ../library/features/mvc-page-pattern-and-app-skeleton.md
 ---
@@ -42,10 +43,12 @@ related:
 simple interfaces, gated by Client_True staff persona. It is modeled on `togaview` and depends on
 the `library` core. Auth comes via the SAML gateway `?saml=` handoff; the app owns its own
 session and reads `Client_True` **read-only** — but it is **no longer a read-only app**: as of
-PR tools#13 (unmerged) it also **WRITES** to client tenant databases (`Client_Compass` /
-`Client_CompassCanada`) through new `[database_compass]` / `[database_compasscanada]` ini
-sections that reuse the `[database_true]` account. That is the first non-read-only surface in
-Tools. Adding a tool = create `mvc/<route>/get.php`
+PR tools#13 (**merged to `_production` 2026-09-04**) it **WRITES** to client tenant databases
+(`Client_Compass` / `Client_CompassCanada`) through the `[database_compass]` /
+`[database_compasscanada]` ini sections, and PR tools#14 (**open**) adds writes to `Users`
+identity fields (email, phone, cost center) plus staff-actor audit rows in `Logs_Compass` /
+`Logs_CompassCanada` via two more ini sections — all four reusing the `[database_true]` account.
+That is the first non-read-only surface in Tools. Adding a tool = create `mvc/<route>/get.php`
 (copy `mvc/_TEMPLATE`) + add one `App_Nav::definition()` entry + `App_Auth::requireAuth([...])`.
 
 **Critical rules:** Do NOT use bare `<header>` elements in this app — they inherit the legacy
@@ -68,6 +71,13 @@ persona list (`['Development Team']`) — never `App_Nav::personasForRoute()`**,
 UNION of the folder's personas and the action's personas and so widens the grant straight back to
 everyone who can see the nav group. Also: **persona checks read a 4-day session snapshot**, so
 removing someone's persona does **not** revoke their access — their session must be killed.
+**`App_Database` transactions are GLOBAL** — `beginTransaction()` / `commitTransaction()` /
+`rollbackTransaction()` take no arguments and act on every registered connection, so an audit/log
+row on another connection must be written **before** `beginTransaction()` or it is rolled back with
+the work, and a bare `rollbackTransaction()` leaves autocommit off for the rest of the request
+(silently dropping every later write). **A staff-editable `Users.email` is a login/reset identity**
+— never ship one without a `Core.ClientEmailDomains` domain check and a cross-row duplicate
+refusal, because no Compass tenant has a unique key on `email`.
 
 ## Boot & structure
 

package/knowledge/1.0/apps/tools/features/compass-user-persona-admin.md

@@ -5,7 +5,7 @@ repo: tools
 project: Tools
 client: shared
 type: feature
-status: draft
+status: active
 updated: 2026-09-04
 owners: [ajean]
 files:
@@ -22,31 +22,40 @@ related:
   - ./saml-sso-auth.md
   - ../architecture.md
   - ../../../2.0/apps/_underscore/features/effective-persona-resolution.md
+  - ../../../2.0/apps/_underscore/features/record-change-audit-log.md
+  - ../../../2.0/apps/_underscore/features/user-email-as-identity-and-password-reset.md
   - ../../../clients/compass-usa/features/people-file-user-lifecycle.md
   - ../../../clients/compass-usa/features/persona-model-and-levy-gating.md
+  - ../../../clients/compass-usa/features/cost-centers.md
   - ../../../clients/compass-usa/workflows/granting-persona-bundle-access.md
 ---
 
 ## Summary
 
-Two pages in the Tools `developers` nav folder that let staff do, in a browser, the two Compass
+Two pages in the Tools `developers` nav folder that let staff do, in a browser, the Compass
 requests that used to mean "email a developer, who writes a `dbchanges2` SQL file": **activate /
-deactivate a Compass user**, and **grant a persona**. Both tenants are covered by one tenant
-switcher — **US** (`Client_Compass`) and **Canada** (`Client_CompassCanada`).
+deactivate a Compass user**, **grant a persona**, and (as of 2026-09-04) **fix a user's email,
+phone number and cost center**. Both tenants are covered by one tenant switcher — **US**
+(`Client_Compass`) and **Canada** (`Client_CompassCanada`).
 
 **This is the first thing in `tools` that WRITES to a client tenant database.** Until now the app
 read `Client_True` read-only. That single fact drives most of the design and every open risk below.
 
-Status: built on PR **tools#13**, **not yet merged**. `status: draft` until it ships.
+Status: the two pages shipped on PR **tools#13**, now **merged to `tools/_production`**. The
+field-editing work (email / phone / cost center) is PR **tools#14**, branch
+`feature/compass-user-field-edits`, base `_production` — **open, not merged, not deployed.**
 
 ## Key files / entry points
 
 - **`tools/_/app/compass.php`** — `App_Compass`, all data access for both pages (search, persona
-  resolution, activate/deactivate, grant).
-- **`tools/mvc/compass/users/{get,post}.php`** — user search + activate/deactivate + grant persona.
+  resolution, activate/deactivate, grant, and the three field setters).
+- **`tools/mvc/compass/users/{get,post}.php`** — user search + activate/deactivate + grant persona
+  + edit email / phone / cost center.
 - **`tools/mvc/compass/personas/{get,post}.php`** — inspect one persona and who reaches it.
 - **`tools/_/app/nav.php`** — the two nav entries, inside the existing `developers` folder.
-- **`tools/config.production.ini`** — new `[database_compass]` / `[database_compasscanada]` sections.
+- **`tools/config.production.ini`** — `[database_compass]` / `[database_compasscanada]`, plus the
+  two logs sections `[database_compasslogs]` (`Logs_Compass`) and `[database_compasscanadalogs]`
+  (`Logs_CompassCanada`).
 
 ## How it works
 
@@ -57,6 +66,7 @@ Status: built on PR **tools#13**, **not yet merged**. `status: draft` until it s
 3. **See the personas that user reaches, and WHY** — direct row, own location, or sector.
 4. **Inspect a persona** and list who reaches it, from all three sources.
 5. **Grant a persona** — one `INSERT` into `Users_Personas`.
+6. **Edit email, phone number and cost center** (2026-09-04, PR tools#14).
 
 The "why" column is the point of the tool. Answering "who has persona N" from `Users_Personas`
 alone badly under-reports on Compass, because most users hold their catalogue through their
@@ -65,6 +75,40 @@ framework's own — see
 [Effective persona resolution](../../../2.0/apps/_underscore/features/effective-persona-resolution.md),
 which also carries the measured prod numbers and the "reverse lookups must be set-based" rule.
 
+### The three field edits (PR tools#14)
+
+`App_Compass` gained `setEmail()`, `setPhone()`, `setCostCenter()`, the cost-center helpers
+`searchCostCenters()`, `costCenterLocation()`, `personasForLocation()`, `collapsePersonaRows()`,
+the audit writer `logChange()`, and the validators `normaliseEmail()`, `normalisePhone()`,
+`emailDomainIsRegistered()`, `usersWithEmail()`, `isCrossRegionProtectedEmail()`.
+
+**No schema change.** Each edit writes the `Users` row **and** the matching primary `Contacts`
+child row inside **one transaction** — the same mirror the nightly importer maintains (see the
+Contacts-mirror gotcha in
+[PEOPLE-file User Lifecycle](../../../clients/compass-usa/features/people-file-user-lifecycle.md)).
+
+**A staff-editable `Users.email` is a security-sensitive control, not a cosmetic field** — it is
+the key the 2.0 forgot-password flow and login resolve on. Read
+[User email as identity & the password-reset chain](../../../2.0/apps/_underscore/features/user-email-as-identity-and-password-reset.md)
+before touching this code. These are the rails the email edit shipped with, and they are the
+conditions of the decision below — **do not remove one without re-opening it**:
+
+1. The address must be **typed twice** and match.
+2. Its **domain must exist in `Core.ClientEmailDomains`** (`emailDomainIsRegistered()`).
+3. The edit is **refused if any other `Users` row in that tenant already holds the address**
+   (`usersWithEmail()`) — the database will not stop you, see the gotcha below.
+4. The edit is **refused until the operator confirms** when the target row has duplicate twins
+   (the same human on two `Users` rows).
+5. The four `ensureCrossRegionUsersActive()` addresses are **blocked as both source and target**
+   (`isCrossRegionProtectedEmail()`), because that hardcoded worker2 list matches on email.
+6. The **audit row is written before the write**, on its own connection (see the transaction
+   gotcha below).
+
+Cost center is a **picker over distinct codes**, never a type-ahead (the table is ~910k active Unit
+rows — see [Cost Centers](../../../clients/compass-usa/features/cost-centers.md)), and it forces a
+**before/after persona diff** to be shown and confirmed, because a location change moves the user's
+sector and therefore their catalogue.
+
 ### Access gating is deliberately tighter than the folder
 
 Both pages `requireAuth(['Development Team'])` — narrower than the `developers` folder's own
@@ -72,16 +116,35 @@ persona set. That is on purpose: these are tenant **writes**, not read-only deve
 Passing `App_Nav::personasForRoute()` here would widen the grant back to the folder's set; see the
 nav-narrowing gotcha in [MVC data access patterns](./mvc-data-access-patterns.md).
 
+### Audit trail — the tenant Logs DB, no schema change
+
+The "no staff-actor audit trail exists" open item is **resolved**. A staff-actor row **can** be
+written to `Logs_<Tenant>.Record` with no schema change, because `Record.userId` is **nullable**:
+
+- `recordId` = **2** (`Core.Records` id for `Users`), `primaryKeyId` = the target `Users.id`,
+  `clientId` = the tenant's `Core.Clients` id, `userId` = **NULL**, staff identity in **`note`**.
+- This is the shape `_Model_Compass_ApprovalDecision`
+  (`_underscore/Model/Compass/ApprovalDecision.php:1344-1366`) already hand-writes, so it is an
+  established pattern, not a new invention.
+- **`Record.note` is `varchar(255)` = 255 CHARACTERS.** Truncate with **`mb_substr`**, never
+  `substr` — byte truncation of a 262-character note produced 155 bytes of invalid UTF-8 in a live
+  test.
+
+That is why `[database_compasslogs]` and `[database_compasscanadalogs]` exist. Details and the
+cross-cluster rules: [Record Change Audit
+Log](../../../2.0/apps/_underscore/features/record-change-audit-log.md).
+
 ### Database connections
 
-New `[database_compass]` and `[database_compasscanada]` sections in `config.production.ini` reuse the
-**existing `[database_true]` account** — same client cluster, only `dbname` differs. **No new secret
-value was introduced.** See the accepted risk below.
+The `[database_compass]` / `[database_compasscanada]` sections, and the two logs sections, all
+reuse the **existing `[database_true]` account** — same client cluster, only `dbname` differs.
+**No new secret value was introduced.** See the accepted risk below.
 
 ### Schema footprint: none
 
-The tool creates and alters **nothing**. It reads/writes only `Users`, `Users_Personas`,
-`Locations_Personas`, `Locations`, and reads `Personas` for names.
+The tool creates and alters **nothing**. It reads/writes only `Users`, `Contacts` (+ its primary
+email/phone children), `Users_Personas`, `Locations_Personas`, `Locations`, reads `Personas` for
+names, reads `Core.ClientEmailDomains` / `Core.Clients`, and inserts into `Logs_<Tenant>.Record`.
 
 ## Decisions
 
@@ -92,6 +155,19 @@ The tool creates and alters **nothing**. It reads/writes only `Users`, `Users_Pe
   and then **closed unmerged** — do not resurrect them without re-opening that decision.
 - **2026-09-04 — Reuse the `[database_true]` credential** rather than split out a least-privilege
   Compass account. Raised twice in security review and consciously declined for now (see below).
+- **2026-09-04 — Ship all three fields (email, phone, cost center), not phone-only (ajean).** The
+  independent architecture and security reviews both recommended shipping **phone only** and
+  deferring email. The developer was shown both and chose to ship all three **with the six safety
+  rails listed above**. Those rails are the conditions the decision was made under: removing the
+  domain allowlist, the cross-row duplicate refusal, the typed-twice confirmation, or the
+  audit-before-write re-opens the decision and needs a fresh security review.
+- **2026-09-04 — Cost-center edits are deliberately TEMPORARY (ajean).** `setCostCenter()` writes
+  `Users.locationId` and `Users.c_erpEntityId` but **not** `Users.c_erpSystemEntityId`, so for any
+  user in the nightly PEOPLE file the change is undone that night when the importer re-resolves
+  `locationId` from the employee key. Chosen over corrupting the employee directory key —
+  `c_erpSystemEntityId` is also copied into `c_hrEmpDirectoryKey` and treated as unique per
+  employee. Same one-way-durability shape as the activation gotcha. Detail:
+  [Cost Centers](../../../clients/compass-usa/features/cost-centers.md).
 
 ## Gotchas
 
@@ -100,34 +176,89 @@ The tool creates and alters **nothing**. It reads/writes only `Users`, `Users_Pe
   absent from that day's file — so an activation only sticks if the person is actually in the file.
   Deactivation holds, because the cron never reactivates anybody. Full lifecycle:
   [PEOPLE-file User Lifecycle](../../../clients/compass-usa/features/people-file-user-lifecycle.md).
+- **⚠ A cost-center edit is undone the same night for anyone in the PEOPLE file** — by design, see
+  the decision above. Set expectations with the requester; it is a stop-gap, not a fix.
+- **⚠ The database will silently accept a duplicate email — the duplicate check MUST live in code.**
+  Prod-verified 2026-09-04: **neither** `Client_Compass.Users` nor `Client_CompassCanada.Users` has
+  a `UNIQUE KEY` on `email` (nor any index on it). The blank-client template's `UNIQUE KEY email`
+  does not describe these tenants. `usersWithEmail()` is the only thing standing between a typo and
+  two accounts sharing one login identity. Full index list:
+  [PEOPLE-file User Lifecycle](../../../clients/compass-usa/features/people-file-user-lifecycle.md).
+- **⚠ A per-tenant email-domain allowlist must span BOTH Compass clients.** Real Compass Canada
+  users are on `compass-canada.com`, which is registered in `Core.ClientEmailDomains` to
+  **client 2 (Compass Group / `Compass_Usa`)**, not client 43. Scoping the domain check to the
+  tenant being edited rejects legitimate Canadian staff. `Users.clientId` is also **NULL** on
+  ~178,615 of 178,616 `Client_Compass` rows, so the client id cannot be derived from the user row.
+  See [Compass Canada profile](../../../clients/compass-canada/profile.md).
 - **A cross-region user still needs a code change and a deploy.** The only durable way to hold one
   active is the hardcoded four-address list in `ensureCrossRegionUsersActive()` in
-  `worker2/Worker/Client/Compass/PeopleFile.php`. This tool does not change that.
+  `worker2/Worker/Client/Compass/PeopleFile.php`. This tool does not change that — and because that
+  list matches on **email**, those four addresses are blocked from this tool's email edit entirely.
 - **Every user search is a full table scan.** `Client_Compass.Users` has no index on `email`,
   `c_hrEmpUsername`, `c_hrEmpPersonnelNbr` or `isActive` (176k rows; `EXPLAIN` reports `type=ALL`,
   no possible keys). Same on `Client_CompassCanada`. Keep result sets bounded and do not add
-  per-row lookups against those columns in a loop.
+  per-row lookups against those columns in a loop. The cost-center search is the same story —
+  `Locations` has no usable index for it either, which is why it is a picker, not a type-ahead.
 - **⚠ Accepted risk — the tool widens the blast radius of one shared credential.** It points the
-  `[database_true]` account at two more tenant schemas. `config.production.ini` is committed and was
-  web-readable until the 2026-07-24 `FilesMatch` deny blocks, so **rotation of that account is still
-  owed**. An inline comment in the ini records this and lists the exact grants a split-out Compass
-  account would need. Never paste the value anywhere.
+  `[database_true]` account at four more schemas (two tenants + two logs). `config.production.ini`
+  is committed and was web-readable until the 2026-07-24 `FilesMatch` deny blocks, so **rotation of
+  every secret in that file is still owed**. A least-privilege Compass account would shrink the
+  blast radius of that shared credential, which also reaches `Client_True` — where the
+  `Development Team` persona rows that gate this very tool live. An inline comment in the ini
+  records this and lists the exact grants a split-out account would need. Never paste the value
+  anywhere.
 - **⚠ Persona revocation does not take effect for up to 4 days.** Tools snapshots persona names into
   `$_SESSION` at login and sessions last 4 days, so removing someone's `Development Team` persona
   does not lock them out of these pages until their session dies. See
-  [SAML SSO & persona-gated auth](./saml-sso-auth.md).
-- **No staff-actor audit trail exists for these writes.** `Logs_Compass.Record.userId` is a **tenant**
-  `Users.id`, so it cannot record a `Client_True` staff member — it is not usable as the audit log
-  for this tool, and `Logs_Compass.Record` is the client-facing activity log (3.6M rows) besides.
-  See
-  [Record Change Audit Log](../../../2.0/apps/_underscore/features/record-change-audit-log.md).
-  Auditing internal-tool actions remains an open item.
+  [SAML SSO & persona-gated auth](./saml-sso-auth.md). Now that these pages write user identity
+  fields, a **narrower persona for the write actions** is worth considering.
+- **⚠ `App_Database` transactions are GLOBAL, so the audit write must happen BEFORE
+  `beginTransaction()`.** `beginTransaction()` / `commitTransaction()` / `rollbackTransaction()`
+  take no arguments and act on **every** registered connection. A `Logs_<Tenant>` insert issued
+  inside the transaction belongs to it and disappears on rollback — exactly when you most want the
+  audit row. A bare `rollbackTransaction()` also leaves autocommit off for the rest of the request.
+  Full footgun: [MVC data access patterns](./mvc-data-access-patterns.md).
 - **Detecting a no-op UPDATE needs `App_Database::affectedRows()`** — `App_Database::query()` returns
   the `App_Query` execute result, not a row count. Details in
   [MVC data access patterns](./mvc-data-access-patterns.md).
+- **Strip line breaks out of anything you log or email.** `App_Page::getVarIfSet()` does **not**
+  remove newlines, so a request value can forge extra `error_log()` lines. Use
+  `App_String::stripBreaksAndTabs()`. It matters for the email field too: a stray line break or
+  degree sign survives the filter, stores fine, escapes fine, and then makes PHPMailer silently
+  drop the recipient. See [MVC data access patterns](./mvc-data-access-patterns.md).
+
+## Open follow-ups (other repos)
+
+- **dbchanges2** — add index `Locations (locationTypeId, isActive, c_erpSystemEntityId)` in **both**
+  Compass tenants; the cost-center search currently reads the whole table.
+- **_underscore** — fix `_Model_Compass_SalesOrder::_costCenter()`
+  (`_underscore/Model/Compass/SalesOrder.php:287-305`): it joins
+  `INNER JOIN Contacts ON Contacts.id = Users.id`, which should be `Users.contactId`.
+- **worker2** — scope `ensureCrossRegionUsersActive()` to a `Users.id` list instead of matching on
+  email; that would also lift this tool's block on those four addresses.
+- **ops** — rotate every secret in `tools/config.production.ini`; consider a least-privilege
+  Compass account.
 
 ## Change history
 
+- 2026-09-04 — Added **email, phone and cost-center editing** (PR tools#14,
+  `feature/compass-user-field-edits`, **open / not merged / not deployed**): new `App_Compass`
+  setters plus the `normaliseEmail` / `normalisePhone` / `emailDomainIsRegistered` /
+  `usersWithEmail` / `isCrossRegionProtectedEmail` validators, a cost-center picker with a mandatory
+  before/after persona diff, and a `Users` + primary `Contacts` write in one transaction. No schema
+  change. Recorded the decision to ship **all three** fields against independent
+  architecture/security advice to defer email, and that the six safety rails (typed twice,
+  `Core.ClientEmailDomains` domain check, cross-row duplicate refusal, duplicate-twin confirmation,
+  cross-region address block, audit-before-write) are the conditions of that decision. Recorded that
+  **cost-center edits are deliberately temporary** because `c_erpSystemEntityId` is not overwritten.
+  **Resolved the "no staff-actor audit trail" open item** — `Logs_<Tenant>.Record.userId` is
+  nullable, so `recordId = 2` (`Users`) + `primaryKeyId` + staff identity in `note` works with no
+  schema change (`note` is 255 **characters** — truncate with `mb_substr`); hence the new
+  `[database_compasslogs]` / `[database_compasscanadalogs]` ini sections, still on the existing
+  `[database_true]` account. Prod-verified that **neither tenant has a `UNIQUE KEY` on
+  `Users.email`**, so the duplicate check must live in code, and that `compass-canada.com` is
+  registered to Compass **USA** (client 2), so an email-domain allowlist must span both Compass
+  clients. Marked PR tools#13 **merged** and the doc `active`. (ajean)
 - 2026-09-04 — Initial: built the two-page Compass user/persona admin (PR tools#13, unmerged) — the
   first `tools` pages that write to a client tenant DB, gated to `Development Team` only, with a
   US/Canada switcher and new `[database_compass]` / `[database_compasscanada]` ini sections reusing

package/knowledge/1.0/apps/tools/features/github-audit.md

@@ -0,0 +1,185 @@
+---
+title: GitHub Audit (monthly code-churn report)
+framework: "1.0"
+repo: tools
+project: Tools
+client: shared
+type: feature
+status: active
+updated: 2026-09-04
+owners: [jcardinal]
+files:
+  - tools/_/app/github/audit.php
+  - tools/mvc/developers/github-audit/get.php
+  - tools/mvc/developers/github-audit/post.php
+  - tools/_/app/nav.php
+related:
+  - ../architecture.md
+  - ./design-demo-admin.md
+  - ../../../standards/frontend.md
+  - ../features/persona-gated-navigation.md
+  - ../../test/features/github-audit-script.md
+---
+
+## Summary
+
+An internal report at **`/developers/github-audit`** (Developers nav group, personas
+`['Development Team','TOGa Technology']`) that shows, for one calendar month, the **lines
+added/removed across every repo in the `agilantsolutions` GitHub org**, plus commit count,
+unique authors, and active repo count. Built so the team gets a monthly code-churn report
+without leaving GitHub.
+
+It is the app port of the standalone
+[`test/team/github_audit.php`](../../test/features/github-audit-script.md)
+script (built first, then moved into Tools). The engine reuses the **Design tool's GitHub
+plumbing** — same token, same log-detail/return-generic error pattern.
+
+## Key files / entry points
+
+- `_/app/github/audit.php` — class **`App_Github_Audit`**: a static, read-only GitHub REST
+  engine (not a Controller/Model). Mirrors the sibling `App_Design_Github` static-engine
+  pattern.
+- `mvc/developers/github-audit/get.php` — the page: native `<input type="month">` picker
+  (defaults to last month), a Run button, a progress bar, and results (summary cards +
+  per-repo table). Themed with `--c-*` tokens (light/dark).
+- `mvc/developers/github-audit/post.php` — AJAX JSON endpoint. `requireAuth` +
+  `App_Page::validateCrossSiteRequestForgery()`; allowlisted actions only.
+- `_/app/nav.php` — one nav action under the `developers` group.
+
+## How it works
+
+### Shared token (depends on the Design tool)
+
+The audit engine does **not** define its own token config. It reuses
+`App_Design_Github::token()` — the `GITHUB_TOKEN` env property first, then the
+`[design] github_token` config fallback. So the GitHub token is **shared** between the
+Design tool and the audit tool, which drives the concurrency lock below.
+
+### Accuracy — per-commit exact counting
+
+To get exact line counts, the engine lists **each commit** in the month window
+(`since`/`until`), then fetches **each commit's stats**. Merge commits are **skipped** (they
+would double-count), and forks are **skipped**.
+
+### Excluded repos
+
+`App_Github_Audit` has a top-of-class `const EXCLUDED_REPOS = ['test', 'claude'];` — a small
+list of repo names to skip entirely. Matched **case-insensitively** in `fetchRepos()`, so
+those repos never enter the run. Add more names here to skip them later. This is in addition
+to the existing skip-forks / (optional) skip-archived filters.
+
+### Two-phase run + real progress bar
+
+The report can hit hundreds of API calls, so the run is split so the page can show true
+progress:
+
+1. `action=repos` — one call that lists all org repos.
+2. `action=repo` — audits **one** repo per request (repo N of total).
+
+The client accumulates totals and authors across the per-repo responses and renders at the
+end. If the run stops midway, it shows **partial results**.
+
+### Reliability — retries and a budget gate at 1000 calls
+
+- GitHub `202` "stats not ready" → retried, then counted as `0` if still not ready.
+- Secondary / abuse rate limit (`403` + `Retry-After`) → retried.
+- **Budget gate** — `const MIN_REMAINING_TO_RUN = 1000;` sets the floor. Enforced at two
+  points, both throwing a user-safe (`ERR_USER_SAFE`) message:
+  - **Pre-flight:** `App_Github_Audit::assertBudget()` calls `GET /rate_limit` (which does
+    **not** count against the rate limit) at the start of a run. If the shared token's core
+    `remaining` is **at or below 1000**, it refuses to start and the scan never begins.
+  - **Mid-run:** `assertRateLimitOk()` **stops** the run once `x-ratelimit-remaining` drops
+    to 1000 — read from headers already returned, so no extra calls — and shows partial
+    results.
+- This replaced the earlier tiny `RATE_LIMIT_FLOOR=25` safety. Rationale: the GitHub token is
+  **shared with the Design tool**, so the audit must leave a healthy budget for other work.
+
+### Live API-call + budget counter
+
+- `App_Github_Audit::callCount()` — calls made in this PHP request.
+- `App_Github_Audit::rateLimit()` — GitHub `x-ratelimit-*` headers (used / remaining /
+  limit / reset).
+
+The page shows a live line: `API calls this run: N · GitHub budget: X of 5,000 left`, and
+the total in the results caption.
+
+### Per-session concurrency lock (shared-token protection)
+
+`post.php` takes an **APCu lock** (`apcu_add`, key `gha_audit_lock_<session_id>`, 300s TTL)
+so only one audit request runs at a time per session. Reason: the GitHub token is **shared**
+with the Design tool, so parallel scans would burn the org's rate limit for everyone. If
+APCu is unavailable the lock is skipped cleanly.
+
+- **Known limit:** APCu is per-EB-instance, so the lock is **per-instance**, not global.
+
+### Error sanitizing
+
+Only a **user-safe** `RuntimeException` (the rate-limit notice, thrown with code
+`App_Github_Audit::ERR_USER_SAFE`) reaches the browser. Every other `RuntimeException` /
+`Throwable` is logged and returned as a **generic** message — GitHub's raw text and repo
+names never surface. Same log-detail / return-generic pattern as
+`App_Design_Github::commitError()`.
+
+### Input validation & SSRF guard
+
+- **Month:** must match `^\d{4}-\d{2}$` **and** month number 01–12. The regex alone accepts
+  `2026-99`, which `DateTime::createFromFormat` silently overflows.
+- **Repo name:** must match `^[A-Za-z0-9._-]{1,100}$` and is rejected if it contains `..`.
+- `org` / `repo` / `sha` are `rawurlencode`'d.
+- `$_POST` reads are guarded with `is_string()` before the `(string)` cast — an array value
+  would raise an **uncatchable** PHP warning → `App_Error` exit → HTML instead of JSON.
+- **SSRF:** host is pinned to `api.github.com`; Link-header pagination is followed only when
+  the host is still `api.github.com`; curl is pinned to `CURLPROTO_HTTPS` with SSL verify on.
+
+## Access control
+
+Behind Tools SSO. `get.php` and `post.php` self-guard with `requireAuth` +
+`App_Page::validateCrossSiteRequestForgery()`; the nav action is gated to the
+`Development Team` and `TOGa Technology` personas.
+
+## GitHub token
+
+No new config. Uses `App_Design_Github::token()` — see
+[Design Demo Admin › GitHub token](./design-demo-admin.md). Value never recorded, logged, or
+echoed.
+
+## Client variations
+
+None — internal/shared developer tool.
+
+## Gotchas / known issues
+
+- **The `hidden` attribute is beaten by a class `display:` rule.** The results/spinner box
+  had the HTML `hidden` attribute but still showed on load (looked like the tool auto-ran),
+  because an author `display:flex` class rule beats the UA `[hidden]{display:none}`. Fix: a
+  scoped guard `.<scope> [hidden] { display:none !important; }` (or `:not([hidden])` on the
+  display rule). General server-rendered-UI trap.
+- **`curl_close()` is fatal on PHP 8.5** in the 1.0 framework (deprecation → `ErrorException`
+  → aborted request). The audit engine avoids `curl_close()` — same rule as the Design tool.
+  See [Tools architecture](../architecture.md) and framework-rules.
+- **APCu lock is per-EB-instance**, so the single-run guard is per-instance, not org-wide.
+- **Shared rate-limit budget** — this tool and the Design tool draw on the same GitHub token,
+  so a big audit eats into the Design tool's budget and vice versa.
+
+## Change history
+
+- 2026-09-04 — Added `EXCLUDED_REPOS = ['test','claude']` (case-insensitive skip in
+  `fetchRepos()`). Replaced `RATE_LIMIT_FLOOR=25` with a 1000-call budget gate
+  (`MIN_REMAINING_TO_RUN`): pre-flight `assertBudget()` via free `GET /rate_limit`, plus
+  mid-run `assertRateLimitOk()` stop — both user-safe — to leave budget for the shared Design
+  tool token. (jcardinal)
+- 2026-09-04 — Created. New `/developers/github-audit` report over the `agilantsolutions` org
+  (lines +/-, commits, unique authors, active repos, per month). Per-commit exact counting
+  (merges/forks skipped), 202 + secondary-rate-limit retries with a primary-limit floor,
+  two-phase repos→repo progress, live API-call/budget counter, per-session APCu concurrency
+  lock (shared Design-tool token), user-safe-only error surfacing, and month/repo input +
+  SSRF hardening. Ported from `test/team/github_audit.php`. (jcardinal)
+
+## Related docs
+
+- [Tools Architecture](../architecture.md)
+- [Design Demo Admin](./design-demo-admin.md) — source of the shared GitHub token and error pattern
+- [Front-End Standards](../../../standards/frontend.md)
+- [github_audit.php standalone script](../../test/features/github-audit-script.md)
+</content>
+</invoke>