toga-ai 1.0.219 → 1.0.221

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

@@ -7,7 +7,7 @@
 | [Assortment Name Translation (AssortmentTranslations sidecar)](features/assortment-name-translation.md) | Serves Assortment (product-grouping) **names** in multiple languages by adding a per-language **sidecar** table `AssortmentTranslations`, reusing the platform's | _underscore/Model/Client/AssortmentTranslation.php, dbchanges2/Client/2026-06-26a - AssortmentTranslations.sql, dbchanges2/Core/2026-06-26a - AssortmentTranslationsRecord.sql, dbchanges2/Client/2026-06-26b - AssortmentTranslationsAcl.sql |
 | [Carrier Shipping Labels (UPS/FedEx) & NetSuite Item Fulfillment](features/carrier-shipping-labels.md) | Backend mechanics behind TOGa Supply's Fulfill & Ship: buying a carrier label (UPS/FedEx), persisting it, and creating the NetSuite Item Fulfillment with tracki | _underscore/Model/Client/ItemFulfillment.php, _underscore/Model/Client/ItemFulfillments/TrackingNumber.php, _underscore/Component/Library/LabelPdf/LabelPdf.php, _underscore/Component/Library/Carriers/Ups/Ups.php, _underscore/Component/Library/Carriers/Fedex/Fedex.php, _underscore/Trait/Netsuite/ItemFulfillment.php, _underscore/Trait/Netsuite/SalesOrder.php, _underscore/Component/Library/NetSuite/NetSuite.php, _underscore/Model/Client/TrackingNumber.php, _underscore/Model/Client/ShippingMethod.php, _underscore/Model.php, _underscore/Cloud.php |
 | [Client Email Template Sending](features/email-template-sending.md) | `_Model_Client_EmailTemplate` sends a stored, client-defined email template by UUID. | _underscore/Model/Client/EmailTemplate.php, _underscore/Model/Client/EmailTemplateOutgoingEmailAddress.php, _underscore/Email.php |
-| [Forecast.Sales NetSuite import engine (real-time webhook)](features/forecast-sale-import.md) | Real-time importer that takes a NetSuite **sale** record and writes its lines into `Forecast.Sales` (the Forecast2 revenue table). | _underscore/Component/Forecast/SaleImport/SaleImport.php, _underscore/Component/Forecast/Db/Db.php, _underscore/Component/Api/Netsuite/Netsuite.php, worker2/Worker/Netsuite/Invoice.php, worker2/Worker/Netsuite/CashSale.php, worker2/Worker/Netsuite/CreditMemo.php, worker2/Worker/Netsuite/CashRefund.php, worker2/Worker/Netsuite/JournalEntry.php, worker2/Worker/Netsuite/Opportunity.php, worker2/Worker/Netsuite/SalesOrder.php, dbchanges2/Forecast/2026-06-26a - Add journalEntry to Sales transaction type enum.sql, test/@dave/test_invoice_lifecycle.php, test/@dave/test_je_lifecycle.php, test/@dave/test_creditmemo_lifecycle.php, test/@dave/test_cashsale_lifecycle.php, test/@dave/test_cashrefund_lifecycle.php, test/@dave/test_fetchrecord_routes.php, test/@dave/NetSuite/api-message-queue/ue_api_msg_queue_enqueue.js, test/@dave/NetSuite/api-message-queue/dev_ue_api_msg_queue_enqueue.js |
+| [Forecast.Sales NetSuite import engine (real-time webhook)](features/forecast-sale-import.md) | Real-time importer that takes a NetSuite **sale** record and writes its lines into `Forecast.Sales` (the Forecast2 revenue table). | _underscore/Component/Forecast/SaleImport/SaleImport.php, _underscore/Component/Forecast/Db/Db.php, _underscore/Component/Api/Netsuite/Netsuite.php, worker2/Worker/Netsuite/Invoice.php, worker2/Worker/Netsuite/CashSale.php, worker2/Worker/Netsuite/CreditMemo.php, worker2/Worker/Netsuite/CashRefund.php, worker2/Worker/Netsuite/JournalEntry.php, worker2/Worker/Netsuite/Opportunity.php, worker2/Worker/Netsuite/SalesOrder.php, dbchanges2/Forecast/2026-06-26a - Add journalEntry to Sales transaction type enum.sql, test/@dave/test_invoice_lifecycle.php, test/@dave/test_je_lifecycle.php, test/@dave/test_creditmemo_lifecycle.php, test/@dave/test_cashsale_lifecycle.php, test/@dave/test_cashrefund_lifecycle.php, test/@dave/test_fetchrecord_routes.php, test/@dave/verify_je_classification.php, test/@dave/probe_je_accounts.php, test/@dave/NetSuite/api-message-queue/ue_api_msg_queue_enqueue.js, test/@dave/NetSuite/api-message-queue/dev_ue_api_msg_queue_enqueue.js |
 | [_Model magic-field access (__get without __isset)](features/model-magic-field-access.md) | `_Model` exposes DB columns as "magic" properties via `__get()`, but it defines **no** `__isset()`. | _underscore/Model/Core/Model.php |
 | [NetSuite REST Client (_Component_Api_Netsuite) — record writes & SuiteQL](features/netsuite-rest-client.md) | `_Component_Api_Netsuite` is the **2.0 `_underscore` NetSuite REST client** — the shared primitive every worker2/api2 NetSuite caller uses for record GETs, Suit | _underscore/Component/Api/Netsuite/Netsuite.php |
 | [Per-Client Database Connections & the Local Logs Trap](features/per-client-database-connections.md) | When `_underscore` serves a request for a client it opens **three distinct per-client database connections**, not one. | _underscore/Database.php, _underscore/ApiRequest.php, _underscore/Model/Client/Logs/Api.php |

package/knowledge/2.0/apps/_underscore/features/forecast-sale-import.md

@@ -26,6 +26,8 @@ files:
   - test/@dave/test_cashsale_lifecycle.php
   - test/@dave/test_cashrefund_lifecycle.php
   - test/@dave/test_fetchrecord_routes.php
+  - test/@dave/verify_je_classification.php
+  - test/@dave/probe_je_accounts.php
   - test/@dave/NetSuite/api-message-queue/ue_api_msg_queue_enqueue.js
   - test/@dave/NetSuite/api-message-queue/dev_ue_api_msg_queue_enqueue.js
 related:
@@ -167,11 +169,25 @@ item-line upsert/reconcile machinery (`syncLines`/`guardedInsert`/`deleteRows`).
 - Lines hitting a **revenue** or **cost** GL account are grouped by **(salesRep, item)**:
   `revenue = Σ(credit − debit)` over revenue lines, `cost = Σ(debit − credit)` over cost
   lines, `profit = revenue − cost`.
-- **Account classification is done on the fly by NetSuite `accttype`** — SuiteQL
-  `SELECT id, accttype FROM account WHERE id IN (...)`, cached per run, bucketed via a tunable
-  `JE_ACCTTYPE_BUCKETS` map. It is **NOT** a hardcoded account-id list. PROVISIONAL default:
-  `Income → revenue`, `COGS → cost` (pending sales-team sign-off; open questions: whether
-  `OthIncome`/`Expense` count, and the Income-typed but "Cost"-named accounts 430/433).
+- **Account classification is an EXACT account-NUMBER allowlist** (sales-team-defined; this
+  *replaced* the old provisional `accttype`-bucket rule). Constants in
+  `_Component_Forecast_SaleImport`: `JE_REVENUE_ACCOUNT_NUMBERS = ['41100','41300','41500']`,
+  `JE_COST_ACCOUNT_NUMBERS = ['51100','51200']`. Any line whose account number is in neither
+  list is **ignored**. The helper `accountNumbers(accountIds)` (which **replaced**
+  `accountTypes()`) resolves each line account's `acctnumber` via SuiteQL
+  `SELECT id, acctnumber FROM account WHERE id IN (...)`, cached per run; matching is
+  **string membership of `acctnumber`**, not `accttype`.
+- **Sub-accounts are EXCLUDED by design — exact match, never prefix.** This chart of accounts
+  has real traps that both a `accttype` rule AND a prefix match would mis-bucket: under **41300**
+  "Service Revenue" sit `41300.01` (Service Revenue-Agent, `accttype` Income), `41300.02`/`.03`
+  (Service Cost-Agent, `accttype` **Bank**), and `41300.04` (Service **Costs**-Agent, `accttype`
+  **Income** despite the cost name); **51200** has `51200.01` (COGS Service-Agent). Exact-number
+  matching sidesteps all of them.
+- **Resolved account map** (number → internalId / name): `41100→245` Product Revenue,
+  `41300→339` Service Revenue, `41500→355` Pre-Sales Consulting; `51100→248` COGS Product,
+  `51200→249` COGS Service. Read-only resolver tool: `test/@dave/probe_je_accounts.php`.
+- **Likely future one-line tweak:** if the Agent sub-accounts should count, add `41300.01` to
+  the revenue list and `51200.01` to the cost list.
 - Group key uses `json_encode([salesRep, item])` (not a string-join) to stay collision-safe
   once the fields go live — an empty-string separator would let `"5|" + null` collide.
 
@@ -281,6 +297,12 @@ live `_Component_Api_Netsuite::createRecord()` `#`-delimiter bug (still unfixed;
 5. **delete** the record.
 6. **verify** the local row is gone (`removeAll`).
 
+> **Scope of the update step (what it does and does NOT cover):** the update step changes
+> **only `tranDate`** — a tracked column, so it forces a real change-detection UPDATE while
+> the amount stays unchanged. It does **NOT** exercise updates to revenue / customer /
+> salesRep / item, nor line add/remove. A future tester verifying those must extend the
+> harness; the current update-step assertion only proves the tracked-column UPDATE path.
+
 Poll the **local** Forecast DB between steps:
 `C:\xampp8\mysql\bin\mysql.exe -u root` → db **`forecast`**, table **`Sales`** (filter on the
 test internalId, or customerId `2` / itemId `25`).
@@ -301,9 +323,16 @@ test internalId, or customerId `2` / itemId `25`).
 - Item **103741** ("Test Other Charge for Sale") → local `forecast.Items` id **25**.
 - Location **5** ("Main") — required as a **header-level** field on creditMemo/cashSale/cashRefund
   and **line-level** on invoice.
-- **JE fixture:** subsidiary **1**; accounts **245** (Product Revenue / Income), **248**
-  (COGS Product / COGS), **215** (Clearing - CSS — ignored, neither revenue nor cost); set a
-  `reversalDate` so NetSuite auto-creates the reversal.
+- **JE fixture:** subsidiary **1**; accounts **245** (Product Revenue, acctnumber **41100**),
+  **248** (COGS Product, **51100**), **215** (Clearing - CSS — ignored, neither revenue nor
+  cost); set a `reversalDate` so NetSuite auto-creates the reversal. Classification is now by
+  **account number** (allowlist), so any clearing/balance line lands outside both lists and is
+  ignored automatically.
+- **Discriminating classification test — `test/@dave/verify_je_classification.php`:** posts one
+  balanced JE `+10/+20/+30` to `41100/41300/41500`, `−5/−7` to `51100/51200`, **plus `+100` to
+  the excluded sub-account `41300.01`**, plus a clearing balance line → local `Forecast.Sales`
+  aggregates to **revenue=60.00, profit=48.00** (NOT 160 — proving `41300.01` is excluded and the
+  exact-number rule is in force).
 
 ### Expected local revenue signs / row outcomes
 - **invoice** → `+` (a **$0** invoice still writes **one** row, revenue `0.00` — the engine does
@@ -382,6 +411,19 @@ record is deleted in NetSuite.)
 - The cron's sign handling is not portable here — see Sign convention.
 
 ## Change history
+- 2026-06-26 — **Changed JE revenue/cost classification from `accttype` buckets to an EXACT
+  account-NUMBER allowlist** (sales-team-defined): `JE_REVENUE_ACCOUNT_NUMBERS =
+  {41100,41300,41500}`, `JE_COST_ACCOUNT_NUMBERS = {51100,51200}`; everything else ignored.
+  `accountNumbers()` (replaced `accountTypes()`) resolves each account's `acctnumber` via
+  SuiteQL, cached per run; match is exact-string, **never prefix** — sub-accounts are excluded
+  by design to dodge real chart-of-accounts traps (`41300.04` "Service Costs-Agent" is
+  `accttype` Income; `41300.02/.03` are `accttype` Bank). Resolved map: 41100→245, 41300→339,
+  41500→355, 51100→248, 51200→249. Verified with a discriminating balanced-JE test
+  (`test/@dave/verify_je_classification.php` → revenue=60.00/profit=48.00, proving `41300.01`
+  excluded); read-only resolver `test/@dave/probe_je_accounts.php`. Future one-liner: add
+  `41300.01`/`51200.01` if Agent sub-accounts should count. Also clarified the e2e harness
+  update step exercises **only `tranDate`** (a tracked column) — not revenue/customer/salesRep/
+  item or line add/remove. (dfranks)
 - 2026-06-26 — **Documented the full e2e testing playbook + harness inventory to run cold**
   (6-step create→verify→update→verify→delete→verify lifecycle; per-type harness action sets;
   the two execution modes — WEBHOOK vs LOCAL-ONLY `sync` — fixtures, expected signs, prod

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

@@ -5,6 +5,7 @@
 | [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 Rich-Text Custom Fields via Quill Delta (API)](features/clickup-richtext-api.md) | ClickUp custom text fields (type `text` and long-text) support rich formatting only through a **Quill Delta** written to the undocumented `value_richtext` key o | test/@dave/clickup_md2delta.js, .claude/skills/plan-ticket/scripts/clickup.js |
 | [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 |
 | [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 |
@@ -15,7 +16,9 @@
 | [NetSuite → Forecast Open-Orders Sync (salesOrder webhook → OpenOrderItems)](features/netsuite-salesorder-open-orders-sync.md) | Webhook-driven, single-record port of the legacy open-orders importer (TRUE-79142). | worker2/Worker/Netsuite/SalesOrder.php, worker2/Worker/Netsuite.php, test/@dave/probe_salesorder_rest_shape.php, test/@dave/probe_open_order_lines.php, test/@dave/check_so_status.php, test/@dave/check_so_history.php, test/@dave/probe_so_rest_lines.php, test/@dave/probe_missing_oo_timing.php, test/@dave/probe_missing_oo_createdby.php, test/@dave/probe_drift_so_dates.php, test/@dave/probe_open_order_gating.php, worker/crons/toga2/forecast2/import_open_orders.php, worker/crons/toga2/forecast2/common_import_sales_from_netsuite.php |
 | [DB-Driven Notification (Internal) Email](features/notification-email.md) | Internal/notification emails (merge-conflict alerts, ops notices — anything system-generated, not client-facing transactional mail) are sent through one worker | worker2/Worker/Notification/Email.php, _underscore/Model/Client/EmailTemplate.php, dbchanges2/Client/2026-06-23a - EmailTemplateWrapper.sql, dbchanges2/Client_True/2026-06-23a - EmailTemplateWrapper.sql |
 | [Startech Webhook Handler (worker2)](features/startech-webhook-handler.md) | Receives inbound webhook events from Startech (Easeedesk) and creates or updates the corresponding ticket in TOGA 2.0. | worker2/Worker/Startech.php |
+| [Talos (TOGa IQ) Meeting-Notes Integration & Token Auto-Refresh (consumer)](features/talos-meeting-notes-integration.md) | How a **dev tool / agent consumes Talos (TOGa IQ)** to query the team meeting-notes corpus programmatically. | .claude/skills/plan-ticket/scripts/talos.js |
 | [Team Sprint Management & Reporting](features/team-sprint-management.md) | `_Worker_Team_Sprint` (file `Worker/Team/Sprint.php`) is the engine behind TOGA's internal **development-sprint process and reporting**. | worker2/Worker/Team/Sprint.php |
 | [Teams Meeting Transcript Export](features/teams-transcript-export.md) | `_Worker_Team_Transcripts` (action `Team/Transcripts/Export`) polls Microsoft Graph for Teams meeting transcripts produced by a set of organizers, classifies ea | worker2/Worker/Team/Transcripts.php, worker2/Config/production.ini, worker2/Database/TeamsTranscriptExports.sql, dbchanges2/Core/2026-06-18a - Teams Transcript Export schedule.sql |
 | [VAPI Webhook Handler (worker2 — AI-BDR end-of-call processing)](features/vapi-webhook-handler.md) | `_Worker_Vapi` ([worker2/Worker/Vapi.php](worker2/Worker/Vapi.php)) is the **PHP side of the AI-BDR call loop** — the webhook that receives VAPI's end-of-call r | worker2/Worker/Vapi.php, worker2/Worker/Ai/Bdr/Vapi.php |
 | [WJE Freshservice Sync (worker2)](features/wje-freshservice-sync.md) | WJE ("WJE IT", helpdesk `wje.freshservice.com`) is a **Freshservice**-based help-desk client whose tickets, contacts, assets, groups, categories, and canned res | worker2/Worker/Wje.php, _underscore/Component/Api/Wje/Wje.php, _underscore/Model/Wje/Ticket.php, _underscore/Model/Wje/TicketNote.php, _underscore/Model/Wje/Contact.php, _underscore/Model/Wje/Unit.php, _underscore/Model/Wje/TicketTeam.php, _underscore/Model/Wje/TicketCategory.php, _underscore/Model/Wje/AssetType.php, _underscore/Model/Wje/PredefinedReply.php, library/app/api/wje.php, worker/crons/toga2/wje/import_supporting_records.php, worker/crons/toga2/wje/sync_togasupply_wje.php, worker/crons/notifications/reports/wje/wje_common.php, library/app/systemmonitor/wje.php, dbchanges2/Client_Wje/2024-10-04 - WjeOnboarding.sql |
+| [Ticket → ClickUp Pseudocode Planning (Talos-grounded)](workflows/ticket-to-pseudocode-planning.md) | A repeatable procedure for turning a ClickUp ticket into a reviewed, formatted implementation plan posted back to the ticket's `📝 Pseudocode` custom field. | test/@dave/clickup_md2delta.js |

package/knowledge/2.0/apps/worker2/features/clickup-richtext-api.md

@@ -0,0 +1,133 @@
+---
+title: ClickUp Rich-Text Custom Fields via Quill Delta (API)
+framework: "2.0"
+repo: worker2
+project: Worker
+client: shared
+type: feature
+status: active
+updated: 2026-06-26
+owners: [dfranks]
+files:
+  - test/@dave/clickup_md2delta.js
+  - .claude/skills/plan-ticket/scripts/clickup.js
+related:
+  - ./netsuite-opportunity-sync.md
+  - ./clickup-project-routing.md
+  - ../workflows/ticket-to-pseudocode-planning.md
+  - ./talos-meeting-notes-integration.md
+---
+
+## Summary
+
+ClickUp custom text fields (type `text` and long-text) support rich formatting only through a
+**Quill Delta** written to the undocumented `value_richtext` key on the Set-Custom-Field-Value
+endpoint. Markdown or HTML written to the documented `value` key renders as literal characters.
+A companion `value` (plain-text fallback) must accompany every richtext write.
+
+## How it works
+
+### Endpoint
+
+`POST https://api.clickup.com/api/v2/task/<taskId>/field/<fieldId>?custom_task_ids=true&team_id=<CLICKUP_TEAM_ID>`
+
+Header: `Authorization: <CLICKUP_API_KEY>` — no `Bearer` prefix.
+
+### Request body
+
+```json
+{
+  "value": "<plain-text fallback>",
+  "value_richtext": "{\"ops\":[...]}"
+}
+```
+
+`value_richtext` must be the Delta JSON **serialized to a string** — not a nested JSON object.
+The outer JSON body is a normal JSON object; only `value_richtext`'s value is a JSON-encoded string.
+
+### Quill Delta format rules
+
+A Delta is `{"ops":[...]}`. Each op is `{"insert": "...", "attributes": {...}}`.
+
+**Block-level formats** attach to the `\n` op that **terminates the block**; they apply back
+to the previous newline. Block attribute keys:
+
+| Format | Key | Values |
+|--------|-----|--------|
+| Heading | `header` | `1`, `2`, `3` |
+| Bullet list | `list` | `"bullet"` |
+| Ordered list | `list` | `"ordered"` |
+| List indent | `indent` | `1`, `2`, … |
+| Code block | `code-block` | `true` |
+| Blockquote | `blockquote` | `true` |
+
+**Inline formats** wrap the text `insert` directly:
+
+| Format | Key | Value |
+|--------|-----|-------|
+| Bold | `bold` | `true` |
+| Italic | `italic` | `true` |
+| Inline code | `code` | `true` |
+| Link | `link` | `"https://..."` |
+
+**No native table op.** Convert markdown tables to bullet lists. Convert horizontal rules
+(`---`) to a blank line — there is no `hr` op in ClickUp's Delta renderer.
+
+Every Delta must end with a bare `{"insert": "\n"}` op.
+
+### Minimal example — a heading followed by a bullet list
+
+```json
+{
+  "ops": [
+    { "insert": "Overview" },
+    { "insert": "\n", "attributes": { "header": 1 } },
+    { "insert": "First item" },
+    { "insert": "\n", "attributes": { "list": "bullet" } },
+    { "insert": "Second item" },
+    { "insert": "\n", "attributes": { "list": "bullet" } },
+    { "insert": "\n" }
+  ]
+}
+```
+
+## Reusable converter
+
+`test/@dave/clickup_md2delta.js` — converts a Markdown file to a Quill Delta and posts both
+`value` and `value_richtext` to a ClickUp custom field.
+
+```sh
+node clickup_md2delta.js <md-path> <TASK_ID> <FIELD_UUID> [--dry]
+```
+
+`--dry` prints the computed Delta without posting. Reads `CLICKUP_API_KEY` and
+`CLICKUP_TEAM_ID` from the environment.
+
+The converter was used to push a full implementation plan into the `📝 Pseudocode` custom
+field (`ad0e4fc8-ff03-4e5f-a187-7d2cd6d0bc65`) on ticket TRUE-79868. The same mechanism is
+reused by the `clickup.js` helper in the local `plan-ticket` skill — see the
+[ticket-to-pseudocode planning workflow](../workflows/ticket-to-pseudocode-planning.md).
+
+## API documentation status
+
+ClickUp's official v2 API docs document only a plain-string `value` for text fields and list
+markdown support as an unfulfilled feature request. The `value_richtext` write path is
+**undocumented but empirically verified** (2026-06-26). It works for both `text` and
+long-text field types.
+
+## Tooling gotcha — PowerShell ConvertTo-Json
+
+PowerShell 5.1 `ConvertTo-Json` pathologically inflates nested strings. A 21 KB
+`value_richtext` string was inflated ~190x (to ~3.8 MB) due to recursive escape-doubling
+of the inner JSON. Avoid `ConvertTo-Json` for ClickUp richtext payloads. Use one of:
+
+- **Node `fetch`** — serialize the body with `JSON.stringify()` directly.
+- **PowerShell + file** — write the JSON body to a UTF-8 file, then pass it to
+  `Invoke-RestMethod -InFile <path> -ContentType "application/json"`.
+- **`System.Web.Script.Serialization.JavaScriptSerializer`** — correctly serializes a
+  pre-built string without re-escaping it.
+
+## Change history
+
+- 2026-06-26 — Cross-linked to the Talos meeting-notes integration and the ticket-to-pseudocode planning workflow; noted the `plan-ticket` skill reuses this richtext write path (dfranks)
+- 2026-06-26 — Initial doc: Quill Delta richtext write path verified; converter tool documented; PowerShell inflation gotcha added (dfranks)

package/knowledge/2.0/apps/worker2/features/talos-meeting-notes-integration.md

@@ -0,0 +1,97 @@
+---
+title: Talos (TOGa IQ) Meeting-Notes Integration & Token Auto-Refresh (consumer)
+framework: "2.0"
+repo: worker2
+project: Worker
+client: shared
+type: feature
+status: active
+updated: 2026-06-26
+owners: [dfranks]
+files:
+  - .claude/skills/plan-ticket/scripts/talos.js
+related:
+  - ../../talos/architecture.md
+  - ./clickup-richtext-api.md
+  - ../workflows/ticket-to-pseudocode-planning.md
+---
+
+## Summary
+
+How a **dev tool / agent consumes Talos (TOGa IQ)** to query the team meeting-notes corpus
+programmatically. Talos itself (the LangGraph Agent Protocol server) is documented under
+[`2.0/apps/talos/`](../../talos/architecture.md); this doc is the **consumer side** — the
+endpoints, assistant, and auth-refresh flow a worker2-side dev script needs to ground its
+output in meeting notes.
+
+**Key distinction:** the `[talos]` key in worker2 config only reaches the **stateless**
+`/api/ai/generate` and `/api/ai/chat` endpoints, which have **no meeting-notes access**.
+Meeting-notes access comes only from **assistants wired to knowledge bases**, reached through
+the Agent Protocol `/threads` + `/threads/{id}/runs/wait` surface with a **user Bearer JWT**.
+
+## How it works
+
+### Server
+
+- Agent Protocol (LangGraph) server: `https://api.togaiq.com`
+- Web app (login / token source): `https://talos.togaiq.com`
+
+### Assistants
+
+Meeting-notes / knowledge-base queries go to a knowledge-wired **assistant**, not the
+stateless generate endpoint.
+
+| Assistant | ID | Use |
+|-----------|-----|-----|
+| **DevCore** | `a5b1833d-b47c-5cb3-8cda-963f1cc74a33` | dev + meeting notes (plan-and-execute agent) |
+| Talos One | — | general |
+| Talos Sales | — | sales |
+| Talos HR | — | HR |
+
+### Querying DevCore
+
+1. `POST /threads` → returns a thread id.
+2. `POST /threads/{id}/runs/wait` with the assistant id and the user message.
+3. DevCore is a **plan-and-execute** agent that **interrupts for plan approval**
+   (agent-inbox schema): the response carries `__interrupt__` with `action: plan_approval`.
+4. **Resume** the run with `command: { resume: [ { "type": "accept", "args": null } ] }`.
+5. The **final answer** is the last item in `messages[]` whose `type` is `"ai"`.
+
+### Authentication & token auto-refresh (verified)
+
+JWTs are issued by `api-writer.togahub.com` with audience `talos.togaiq.com`. This is the
+standard **TOGA 2.0 `/v2/auth/*` flow** (mirrors `api2/Component/Api/V2/V2.php`).
+
+- **Access token** — 1 hour TTL.
+- **Refresh token** — 30 day TTL and **rolls forward** on each refresh (a new refresh token
+  may be returned and must replace the stored one).
+- **Refresh call:**
+  `POST https://api-writer.togahub.com/v2/auth/refresh?transactionId=<unique-uuid>`
+  Header: `Authorization: Bearer <refresh token>`
+  Response: `{ isSuccess, data: { tokens: { access [, refresh] } } }`
+
+**Gotchas (both verified empirically 2026-06-26):**
+
+- The **`/v2` path prefix is REQUIRED** — omitting it returns error **EV-2 "invalid version"**.
+- `transactionId` must be **globally unique per call** — reusing one returns error **EV-5**.
+
+The browser obtains the initial token pair via the `talos.togaiq.com` login. A developer can
+copy `accessToken` + `refreshToken` out of the browser session to seed a local tool, after
+which the tool refreshes on its own.
+
+## Credential storage (location only)
+
+The consumer tool stores its token pair at **`~/.talos/credentials.json`** (user home,
+**outside any repo**). Never commit, echo, or paste the token values anywhere — they are
+secrets. Document only this location.
+
+## Consumer helper
+
+`.claude/skills/plan-ticket/scripts/talos.js` — performs the auth refresh and runs a DevCore
+query (create thread → run → accept plan interrupt → extract final `ai` message). It is part
+of the **local** `plan-ticket` skill, not the team repo; its source is intentionally not
+mirrored into the knowledge base.
+
+## Change history
+
+- 2026-06-26 — Initial doc: consumer-side Talos meeting-notes access via DevCore assistant + the `/v2/auth/refresh` token-rotation flow; stateless `[talos]` config vs. assistant distinction; EV-2/EV-5 gotchas; credential location `~/.talos/credentials.json` (dfranks)

package/knowledge/2.0/apps/worker2/workflows/ticket-to-pseudocode-planning.md

@@ -0,0 +1,60 @@
+---
+title: Ticket → ClickUp Pseudocode Planning (Talos-grounded)
+framework: "2.0"
+repo: worker2
+project: Worker
+client: shared
+type: workflow
+status: active
+updated: 2026-06-26
+owners: [dfranks]
+files:
+  - test/@dave/clickup_md2delta.js
+related:
+  - ../features/clickup-richtext-api.md
+  - ../features/talos-meeting-notes-integration.md
+---
+
+## Summary
+
+A repeatable procedure for turning a ClickUp ticket into a reviewed, formatted implementation
+plan posted back to the ticket's `📝 Pseudocode` custom field. It spans three systems —
+ClickUp (read ticket / write field), the codebase (investigation), and Talos DevCore
+(meeting-notes grounding) — so it is a workflow, not a single feature.
+
+It is implemented as a **local Claude skill** (`.claude/skills/plan-ticket/`) that is **not**
+in the team repo. This doc records the *shape of the procedure* and the durable integration
+mechanics; it does not duplicate the skill source. The two underlying integrations have their
+own feature docs:
+
+- [ClickUp rich-text custom fields via Quill Delta](../features/clickup-richtext-api.md) — how the plan reaches the `📝 Pseudocode` field.
+- [Talos meeting-notes integration](../features/talos-meeting-notes-integration.md) — how the plan is grounded in meeting notes.
+
+## Steps
+
+1. **Fetch the ticket** by id from ClickUp (`custom_task_ids=true`, `team_id` from env).
+2. **Investigate the codebase FIRST** — establish what already exists before asking Talos, so
+   the Talos query is code-informed rather than speculative.
+3. **Query Talos DevCore** (assistant `a5b1833d-b47c-5cb3-8cda-963f1cc74a33`) for
+   meeting-notes context, passing the codebase findings as grounding. Accept the
+   plan-approval interrupt to get the final answer.
+4. **Synthesize a ≤150-line phased plan**, saved to `test/@dave/approach/<TICKET>.md`.
+5. **Preview & approval gate** — show the plan; iterate until the developer approves.
+6. **Push to the ticket's `📝 Pseudocode` field** as a Quill Delta via the richtext write
+   path. The push is **overwrite-guarded**: it refuses to clobber an already-populated field
+   unless run with `--force`.
+
+## Plan document format
+
+`test/@dave/approach/<TICKET>.md` (see also the team convention to store approach plans
+under `test/@dave/approach/`):
+
+- Title heading.
+- Bold header line: **Repos / Framework / Client / Sibling**.
+- Sections, in order: **Summary** · **Meeting-notes context** · **What already exists** ·
+  **Architecture decision** · **Phases** (each with file paths + pseudocode) · **Testing** ·
+  **Risks** · **Owners / open questions** · **Key files**.
+
+## Change history
+
+- 2026-06-26 — Initial doc: ticket→pseudocode planning procedure (ClickUp read → codebase investigation → Talos DevCore grounding → phased plan → approval gate → guarded richtext push); records the shape, not the local skill source (dfranks)

package/knowledge/INDEX.md

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

package/package.json

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