toga-ai 1.0.34 → 1.0.36

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

@@ -3,3 +3,4 @@
 | Doc | Summary | Files |
 |-----|---------|-------|
 | [Library (1.0 Framework) Architecture](architecture.md) | `library` is the shared library repository for **all 1.0 (legacy) applications** — the `App_` framework. | library/_.php, library/app/, library/browser/ |
+| [Elite Freshservice Sync (library)](features/elite-freshservice-sync.md) | `App_Api_Toga2` in `library/app/api/toga2.php` contains three private helpers that handle bidirectional file-attachment sync between TOGA 2 and other systems fo | library/app/api/toga2.php |

package/knowledge/1.0/apps/library/features/elite-freshservice-sync.md

@@ -0,0 +1,93 @@
+---
+title: Elite Freshservice Sync (library)
+framework: "1.0"
+repo: library
+project: Library
+client: elite
+type: client-feature
+status: active
+updated: 2026-06-10
+owners: []
+files:
+  - library/app/api/toga2.php
+related:
+  - clients/elite/profile.md
+  - 2.0/apps/worker2/features/elite-freshservice-sync.md
+---
+
+## Summary
+
+`App_Api_Toga2` in `library/app/api/toga2.php` contains three private helpers that handle
+bidirectional file-attachment sync between TOGA 2 and other systems for Elite:
+
+| Method | Direction | Purpose |
+|---|---|---|
+| `syncFreshserviceConversationAttachmentsIntoToga2` | Freshservice → TOGA 2 | Download attachments from Freshservice presigned S3 URLs and store in TOGA 2 |
+| `syncToga2NoteFilesIntoTogadesk1` | TOGA 2 → TOGaDesk | Copy TOGA 2 note files to TOGaDesk reply attachments |
+| `syncTogadesk1NoteFilesIntoToga2` | TOGaDesk → TOGA 2 | Copy TOGaDesk reply attachments to TOGA 2 note files |
+
+## Key files / entry points
+
+- `library/app/api/toga2.php` — all three methods live here, called from larger
+  sync orchestration methods in the same class
+- `App_Api_Toga2::send()` — the HTTP client used by all three
+
+## How dedup works (all three methods)
+
+All three methods avoid re-uploading files by checking what is already linked before
+uploading. The pattern uses `depth=5` on the parent ticket-note:
+
+```php
+$togaNote = App_Api_Toga2::send($clientUuid, $apiKey, $apiSecret,
+    'GET', '/ticket-notes/' . $ticketNoteUuid, null, ['depth' => 5], true, $endpoint);
+
+$existingFileNames = [];
+foreach (($togaNote->data->ticketNotes->ticketNoteFiles ?? []) as $link) {
+    if (!empty($link->file->name)) {
+        $existingFileNames[] = $link->file->name;
+    }
+}
+```
+
+Dedup is by **filename** — if `$file->name` is already in `$existingFileNames`, skip.
+
+## TOGA 2 API — critical gotchas
+
+**Response key is `ticketNoteFiles`, not `ticketNotesFiles`.**
+The extra `s` before `Files` causes a silent empty array — dedup never fires and files
+get re-uploaded on every sync run. Always use `ticketNoteFiles`.
+
+**`GET /ticket-notes/{uuid}/ticket-note-files` is NOT a list endpoint.**
+This nested route uses `childPolicy = MATCH`:
+- 0 bridge records → 404 EV-6
+- 1 record → 200 single object
+- 2+ records → 404 EV-14 ("multiple found, expected one")
+
+Always use `depth=5` on the parent note for listing — never the nested route.
+
+**`throwExceptionOnApiError` (8th param of `App_Api_Toga2::send()`).**
+Pass `true` for the dedup GET — a valid note UUID should always return 200. Passing
+`false` silently swallows errors and the dedup array stays empty.
+
+## Bridge route for linking files to notes
+
+```php
+// POST /ticket-notes/{uuid}/ticket-note-files
+App_Api_Toga2::send($clientUuid, $apiKey, $apiSecret, 'POST',
+    '/ticket-notes/' . $ticketNoteUuid . '/ticket-note-files',
+    ['file' => ['uuid' => $fileUuid]],
+    null, true, $endpoint);
+```
+
+## Freshservice attachment handling
+
+Freshservice attachment URLs are **presigned S3 URLs that expire**. The sync must run
+immediately at webhook time — do not defer or re-queue the download step.
+
+## TOGaDesk file storage
+
+`syncToga2NoteFilesIntoTogadesk1` writes files to disk at:
+```
+/var/www/html/ontrack/desk/uploads/{id}-{filename}
+```
+Stored as `{id}-{filename}` in the TOGaDesk `files.file` column.

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

@@ -5,3 +5,4 @@
 | [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 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 |
 | [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 |
+| [Elite Freshservice Sync (worker2)](features/elite-freshservice-sync.md) | `_Worker_Elite` processes Freshservice webhook events and syncs them into TOGA 2. | worker2/Worker/Elite.php, worker2/Config/dev-kmaramreddy-laptop.ini |

package/knowledge/2.0/apps/worker2/features/elite-freshservice-sync.md

@@ -0,0 +1,142 @@
+---
+title: Elite Freshservice Sync (worker2)
+framework: "2.0"
+repo: worker2
+project: Worker
+client: elite
+type: client-feature
+status: active
+updated: 2026-06-10
+owners: []
+files:
+  - worker2/Worker/Elite.php
+  - worker2/Config/dev-kmaramreddy-laptop.ini
+related:
+  - clients/elite/profile.md
+  - 1.0/apps/library/features/elite-freshservice-sync.md
+---
+
+## Summary
+
+`_Worker_Elite` processes Freshservice webhook events and syncs them into TOGA 2.
+Dispatched via action `Elite/Webhook` on the worker queue.
+
+## Key files / entry points
+
+- `Worker/Elite.php` — `_Worker_Elite` class, all sync logic lives here
+- `_Component_Api_Elite` (`_underscore`) — authenticated Freshservice HTTP client
+- `_Component_Api_Toga` (`_underscore`) — authenticated TOGA 2 HTTP client
+
+## How the webhook flow works
+
+1. Freshservice fires a webhook to `webhook.togahub.com/elite`
+2. Lambda inserts a `WorkerJobs` row with action `Elite/Webhook`
+3. Worker picks up the job → calls `_Worker_Elite::Webhook($payload, $headers)`
+4. Worker syncs the ticket and all conversations into TOGA 2
+
+## Constants
+
+```php
+const CLIENT_UUID_ELITE = '97627e9d-605f-3ded-9e83-97a4ec7a0c15';
+const API_UUID_ELITE    = 'ee08cf3d-caee-462d-adb5-acc5c36b1f01';
+const API_SECRET_ELITE  = 'c2701d21-1908-4895-aaed-2e6456710e8d';
+```
+
+## Freshservice API — gotchas
+
+**No single-conversation GET endpoint.**
+`GET /api/v2/conversations/{id}` only supports PATCH/PUT/DELETE — it returns 405 on GET.
+To fetch a specific conversation, retrieve the full list for the ticket:
+
+```php
+$conversations = _Component_Api_Elite::send('GET', '/tickets/' . $ticketId . '/conversations', null);
+foreach ($conversations->conversations as $conv) {
+    if ((string) $conv->id === $targetId) { ... }
+}
+```
+
+**Attachment URLs are presigned S3 URLs — they expire.**
+Call the attachment sync method immediately at webhook time. Do not queue the download.
+
+**Attachment shape on a conversation object:**
+```
+$attachment->name
+$attachment->content_type
+$attachment->size
+$attachment->attachment_url   // presigned S3 URL
+```
+
+## TOGA 2 API — gotchas
+
+**`childPolicy = MATCH` nested routes are get-ONE, not a list.**
+`GET /ticket-notes/{uuid}/ticket-note-files` returns:
+- 404 EV-6 when 0 bridge records exist
+- 200 object when exactly 1 exists
+- 404 EV-14 ("multiple found, expected one") when 2+ exist
+
+**Never use this route for listing or dedup.** Use `depth=5` on the parent note instead:
+
+```php
+$togaNote = _Component_Api_Toga::send(..., 'GET', '/ticket-notes/' . $uuid, null, ['depth' => 5], true, $endpoint);
+$existingFileNames = [];
+foreach (($togaNote->data->ticketNotes->ticketNoteFiles ?? []) as $link) {
+    if (!empty($link->file->name)) {
+        $existingFileNames[] = $link->file->name;
+    }
+}
+```
+
+Response key is `ticketNoteFiles` (not `ticketNotesFiles` — no `s` before `Files`).
+
+## Local dev setup
+
+To test worker2 Elite code locally against production TOGA 2 and Freshservice:
+
+1. **Dev config** — `[api]` section needs both keys (`endpoint` for some callers,
+   `_` for `_Config::api('_')`):
+   ```ini
+   [api]
+   _ = "https://api.togahub.com/v2"
+   endpoint = "https://api.togahub.com/v2"
+   ```
+
+2. **`ClientLogs` database** must exist locally — the framework logs every API call there:
+   ```sql
+   CREATE DATABASE IF NOT EXISTS ClientLogs CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_ai_ci;
+   USE ClientLogs;
+   CREATE TABLE `Api` (
+     `id` INT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
+     `uuid` CHAR(36) NOT NULL,
+     `dtStamp` DATETIME NOT NULL,
+     `transactionId` VARCHAR(64) NULL,
+     `apiId` INT UNSIGNED NULL,
+     `userId` INT UNSIGNED NULL,
+     `isAuthRequest` TINYINT UNSIGNED NOT NULL DEFAULT 0,
+     `direction` ENUM('IN','OUT') NOT NULL,
+     `source` VARCHAR(255) NULL,
+     `sourceIp` VARCHAR(45) NULL,
+     `instanceId` VARCHAR(128) NULL,
+     `executionTimeSeconds` DECIMAL(10,4) NULL,
+     `method` VARCHAR(10) NOT NULL,
+     `hostname` VARCHAR(255) NOT NULL,
+     `route` VARCHAR(1024) NOT NULL,
+     `responseCode` SMALLINT UNSIGNED NULL,
+     `queryString` TEXT NULL,
+     `requestHeaders` TEXT NULL,
+     `requestPayload` MEDIUMTEXT NULL,
+     `responseHeaders` TEXT NULL,
+     `responsePayload` MEDIUMTEXT NULL
+   ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci;
+   ```
+
+3. **Bootstrap** for a standalone test script:
+   ```php
+   chdir(__DIR__);
+   putenv('ENVIRONMENT=dev-kmaramreddy-laptop');
+   $_ENV['ENVIRONMENT'] = 'dev-kmaramreddy-laptop';
+   require_once 'vendor/autoload.php';
+   require '_underscore.php';
+   ```
+
+4. **PHP version** — worker2 vendor targets PHP >= 8.5. Local PHP 8.1 requires a
+   temporary bypass in `vendor/composer/platform_check.php` — revert before committing.

package/knowledge/INDEX.md

@@ -4,13 +4,13 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 
 ## 1.0 framework
 
-- **library** (Library) _(framework core)_ — 1 doc(s) → [1.0/apps/library/INDEX.md](1.0/apps/library/INDEX.md)
+- **library** (Library) _(framework core)_ — 2 doc(s) → [1.0/apps/library/INDEX.md](1.0/apps/library/INDEX.md)
 - **worker** (Worker) — 1 doc(s) → [1.0/apps/worker/INDEX.md](1.0/apps/worker/INDEX.md)
 
 ## 2.0 framework
 
 - **_underscore** (_Underscore) _(framework core)_ — 3 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
-- **worker2** (Worker) — 3 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
+- **worker2** (Worker) — 4 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
 - **api2** (API) — 1 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)
@@ -19,4 +19,5 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 
 - **compass-canada** → [clients/compass-canada/INDEX.md](clients/compass-canada/INDEX.md)
 - **compass-usa** → [clients/compass-usa/INDEX.md](clients/compass-usa/INDEX.md)
+- **elite** → [clients/elite/INDEX.md](clients/elite/INDEX.md)
 

package/knowledge/clients/elite/INDEX.md

@@ -0,0 +1,5 @@
+# Client: elite
+
+| Doc | Framework | Summary | Files |
+|-----|-----------|---------|-------|
+| [Elite Client Profile](profile.md) | 2.0 | Elite is a managed-services client that uses **Freshservice** as their helpdesk platform. | worker2/Worker/Elite.php, library/app/api/toga2.php |

package/knowledge/clients/elite/profile.md

@@ -0,0 +1,61 @@
+---
+title: Elite Client Profile
+framework: "2.0"
+project: Worker
+client: elite
+type: client-feature
+status: active
+updated: 2026-06-10
+owners: []
+files:
+  - worker2/Worker/Elite.php
+  - library/app/api/toga2.php
+related:
+  - 2.0/apps/worker2/features/elite-freshservice-sync.md
+  - 1.0/apps/library/features/elite-freshservice-sync.md
+---
+
+## Summary
+
+Elite is a managed-services client that uses **Freshservice** as their helpdesk platform.
+TOGA 2 is the source of truth for tickets, notes, and file attachments. The integration
+keeps Freshservice and TOGA 2 in sync via webhook-driven worker jobs.
+
+## TOGA 2 API credentials
+
+Constants live in `worker2/Worker/Elite.php`:
+
+```php
+const CLIENT_UUID_ELITE = '97627e9d-605f-3ded-9e83-97a4ec7a0c15';
+const API_UUID_ELITE    = 'ee08cf3d-caee-462d-adb5-acc5c36b1f01';
+const API_SECRET_ELITE  = 'c2701d21-1908-4895-aaed-2e6456710e8d';
+```
+
+The library version of the sync methods (`library/app/api/toga2.php`) passes these in as
+parameters — they are not constants there.
+
+## Freshservice instance
+
+- Base URL: `https://eliteservicedesk.freshservice.com`
+- Configured in `_underscore` framework via `_Component_Api_Elite`
+- API logs written to the `ClientLogs` database (`ClientLogs.Api` table) — this DB must
+  exist locally when running worker2 scripts against production Freshservice
+
+## Key custom fields
+
+| TOGA 2 field | Purpose |
+|---|---|
+| `c_eliteTicketId` | Freshservice ticket numeric ID (on `Tickets`) |
+| `c_eliteConversationId` | Freshservice conversation ID (on `TicketNotes`) |
+| `c_eliteUserId` | Freshservice user ID (on `Contacts`) |
+| `c_eliteCategoryId` | Freshservice category ID (on `TicketCategories`) |
+| `c_eliteGroupId` | Freshservice group ID (on `TicketTeams`) |
+
+## Systems involved
+
+| System | Role |
+|---|---|
+| Freshservice | Client helpdesk — source of ticket/conversation events |
+| TOGA 2 (`api2`) | System of record — tickets, notes, contacts, files |
+| worker2 `_Worker_Elite` | Webhook processor — syncs Freshservice events into TOGA 2 |
+| library `App_Api_Toga2` | Shared sync helpers (note-file bidirectional sync) |

package/package.json

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

package/skills/kickoff/SKILL.md

@@ -112,19 +112,45 @@ Ask these in one message. **Present the repos/projects you already know** (read
 
 1. **Framework** — 1.0, 2.0, or **both**?
 2. **Layer** — front-end, back-end, or hybrid?
-3. **Repo(s) / project(s)** — list the registered repos for the chosen framework(s) as
-   options (show `repo` and `project`), plus **"a new repo not listed"**. **This is a
-   multi-select (checkbox), not a single choice.** A session often spans more than one
-   repo/project, so always let the developer pick several. When asking via the question
-   tool, set `multiSelect: true` — never force a single-select (radio) here. If they pick
-   the new-repo option, run **New-repo onboarding** (below) for each new repo before
-   continuing.
-4. **Client** — which client is this for, or "shared / internal"? (List `clients/` folders
-   you know of, plus "a new client".)
+3. **Repo(s) / project(s)** — **list EVERY registered repo for the chosen framework(s)** —
+   do not abbreviate or show only a few. **This is a multi-select (checkbox), not a single
+   choice;** a session often spans more than one repo/project, so always let the developer
+   pick several. If they pick a repo not listed, run **New-repo onboarding** (below) for
+   each new repo before continuing.
+4. **Client** — which client is this for, or "shared / internal"? **List EVERY folder under
+   `knowledge/clients/`** plus "shared / internal" and "a new client" — do not show only a
+   subset.
 5. **What are you building or changing?** (a sentence — used to pick relevant feature docs.)
 
 If any answer is unclear, ask again. Do not guess the framework, repo, project, or client.
 
+### How to present the repo and client choices (questions 3 and 4)
+
+**Do NOT use the option-chip / radio question control for questions 3 and 4.** That
+control caps at ~4 options, which silently truncates the list — with 7+ repos or 3+
+clients the developer never sees the full set. Instead, **render the full list as a
+numbered markdown list in a normal message** and ask the developer to reply with the
+numbers they want (e.g. "1, 3, 5"). This shows every repo and every client with no cap
+and naturally supports multi-select.
+
+```
+**Which repo(s)/project(s)?** (reply with the numbers, multiple OK)
+  1. _underscore  (_Underscore — 2.0 core)
+  2. worker2      (Worker — 2.0 app)
+  3. api2         (API — 2.0 app)
+  ... every registered repo for the chosen framework(s) ...
+  N. a new repo not listed
+
+**Which client?** (one, or "shared / internal")
+  1. compass-canada
+  2. compass-usa
+  ... every folder under knowledge/clients/ ...
+  S. shared / internal
+  X. a new client
+```
+
+Framework (q1) and layer (q2) have ≤4 options, so the chip control is fine for those.
+
 ## Step 3 — Resolve the repos this work needs (local paths, lazily)
 
 Compute the load set with `node "<TEAM_REPO>/knowledge.js" deps --repo=<chosen-repo>`