toga-ai 1.0.220 → 1.0.222

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

@@ -5,7 +5,7 @@
 | [Worker (1.0 Framework) Architecture](architecture.md) | `worker` is the legacy (**1.0** `App_` framework) **background-job tier**. | worker/index.php, worker/_/app/framework.php, worker/crons/, worker/schedules/, worker/ebs/cron.worker.php, worker/.ebextensions/035_cron.worker.config |
 | [Compass MA Sales Order Exception Report](features/compass-ma-sales-order-exception-report.md) | A worker cron that emails operations the "Compass Refresh Exception Report" — Compass `MA%` sales orders whose corresponding Office Depot (ODP) sales order has | worker/crons/toga2/compass/workflow/7_generate_ma_sales_order_exception_report.php |
 | [Compass Partial In-Transit & Delivered Emails (per package)](features/compass-partial-in-transit-delivered-emails.md) | Compass USA and Compass Canada send a **per-package** in-transit email (and a matching delivered email) instead of one email listing the whole order. | worker/crons/toga2/compass/update_salesorder_status_from_odp.php, worker/crons/toga2/compasscanada/workflow/3_update_salesorder_status_from_grand_and_toy.php |
-| [Forecast2 ↔ NetSuite Reconciliation & Trueup Tooling](features/forecast2-netsuite-reconciliation.md) | CLI tools to **audit** and **repair** drift between the production `Forecast` DB (core2) and NetSuite. | test/@dave/reconcile_netsuite_totals.php, test/@dave/fixer.php, test/@dave/analyze_netsuite_forecast_diff.php, test/@dave/trueup_sales.php, test/@dave/trueup_open_orders.php, test/@dave/loop_trueup_open_orders.php, test/@dave/trueup_opportunities.php, test/@dave/probe_sales_gap_direct.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_profit_invoices.php, test/@dave/probe_profit_gap.php, worker/crons/toga2/forecast2/common_import_sales_from_netsuite.php, worker/crons/toga2/forecast2/periodic_forecast_discrepancy_fix_open_orders.php, worker/crons/toga2/forecast2/import_open_orders.php, worker/schedules/cron.worker.infrastructure.json |
+| [Forecast2 ↔ NetSuite Reconciliation & Trueup Tooling](features/forecast2-netsuite-reconciliation.md) | CLI tools to **audit** and **repair** drift between the production `Forecast` DB (core2) and NetSuite. | test/@dave/checker.php, test/@dave/looper.php, test/@dave/reconcile_netsuite_totals.php, test/@dave/fixer.php, test/@dave/analyze_netsuite_forecast_diff.php, test/@dave/trueup_sales.php, test/@dave/trueup_open_orders.php, test/@dave/loop_trueup_open_orders.php, test/@dave/trueup_opportunities.php, test/@dave/probe_sales_gap_direct.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_profit_invoices.php, test/@dave/probe_profit_gap.php, worker/crons/toga2/forecast2/common_import_sales_from_netsuite.php, worker/crons/toga2/forecast2/periodic_forecast_discrepancy_fix_open_orders.php, worker/crons/toga2/forecast2/import_open_orders.php, worker/schedules/cron.worker.infrastructure.json |
 | [NetSuite → TOGa Supply Per-Client Sync (thin wrappers)](features/netsuite-togasupply-per-client-sync.md) | Syncs NetSuite transactions (sales orders, purchase orders, invoices, item receipts, item fulfillments, inventory adjustments) into each TOGa Supply (2.0) clien | worker/crons/toga2/netsuite/common_sync_togasupply.php, worker/crons/toga2/netsuite/sync_togasupply_canon.php, worker/schedules/cron.worker.sync.json, dbchanges2/_modules/netsuite/2026-04-01 - Parameters.sql |
 | [Prudential: Send Shipments for the Day report (daily cron)](features/send-shipments-for-the-day.md) | Daily cron (9:00 PM) that emails Prudential and Dell stakeholders an Excel report of all devices shipped that day, including tracking number, serial number, emp | worker/crons/notifications/reports/send_shipments_for_the_day.php |
 | [Onboarding a Client to the NetSuite TOGa Supply Sync](workflows/onboarding-client-to-netsuite-togasupply-sync.md) | How to add a new TOGa 2 client to the per-client NetSuite → TOGa Supply importer (`worker/crons/toga2/netsuite/`). | worker/crons/toga2/netsuite/sync_togasupply.php, worker/crons/toga2/netsuite/common_sync_togasupply.php, worker/schedules/cron.worker.sync.json, dbchanges2/_modules/netsuite/2026-04-01 - Parameters.sql |

package/knowledge/1.0/apps/worker/features/forecast2-netsuite-reconciliation.md

@@ -6,9 +6,11 @@ project: Worker
 client: shared
 type: feature
 status: active
-updated: 2026-06-25
+updated: 2026-06-26
 owners: [dfranks]
 files:
+  - test/@dave/checker.php
+  - test/@dave/looper.php
   - test/@dave/reconcile_netsuite_totals.php
   - test/@dave/fixer.php
   - test/@dave/analyze_netsuite_forecast_diff.php
@@ -42,6 +44,37 @@ by reconciling a chosen tranDate range directly against NetSuite.
 
 ## Key files / entry points
 
+- `checker.php [--from --to] [--category sales|openorders|opportunities|all] [--verbose] [--no-banner] [--fix --prod]`
+  — **hyper-fast drift detector** using a **moment-fingerprint drill-down** (default window = YTD).
+  Instead of materializing every row on both sides and diffing (the OOM trap that gates `reconcile`'s
+  per-txn diffs), each side computes a **5-number fingerprint PER TIME BUCKET** entirely in-DB in one
+  `GROUP BY`: `n` = COUNT of non-zero-measure records; `rev` = `ROUND(SUM(revenue),2)`;
+  `profit` = `ROUND(SUM(profit),2)` (Sales only); `idSum` = `MOD(SUM(MOD(id,P)),P)`;
+  `idSq` = `MOD(SUM(MOD(id*id,P)),P)`, where `P = 2147483647` (2³¹−1 Mersenne prime). `(rev,profit)`
+  catch **value drift**; `(n,idSum,idSq)` are a **power-sum fingerprint of the id SET** that catches the
+  **compensating case** a plain SUM total can't see (a missing txn masked by an extra txn of equal value).
+  Power-sums are pure integer arithmetic, so they compute **identically on Oracle-flavored SuiteQL and
+  MySQL** (no cross-engine hash-portability problem); `MOD` by the prime keeps the running sums inside
+  64-bit. Compared **top-down, descending only where fingerprints disagree**: L1 `GROUP BY` month → L2
+  `GROUP BY` day (only inside bad months) → L3 per-id list (`--verbose`, reporting only). A clean system
+  **stops at L1 in seconds pulling no rows**. Match identity is the **NetSuite internal id**
+  (`netsuiteTransactionInternalId` / `netsuiteSalesOrderInternalId` / `netsuiteOpportunityInternalId`);
+  date + category are only **scoping/localization**, never identity. Identity (count + id-moments) is
+  computed over **non-zero-measure rows only**, so checker's "in sync" verdict equals fixer.php's "nothing
+  to fix" **by construction** (a missing $0 row is a non-issue). On drift it hands `fixer.php` a **tight
+  day window** (window handoff, not id handoff — see decision below). `--fix` requires `--prod` (auto-runs
+  fixer on the localized window); a **bare run never writes**. Reads the prod core2 **read-replica**
+  directly (same pattern as `reconcile_netsuite_totals.php` / `fixer.php` — creds live in
+  `worker/config.worker.ini` / `CLAUDE.md`, not reproduced here).
+- `looper.php [--interval=60] [--count=0] [--cmd "<verbatim>"] [--args "<extra checker flags>"] [--no-banner] [--no-fix]`
+  — **generic loop runner**, self-contained (no framework bootstrap; shells out via `passthru`). **DEFAULT
+  BEHAVIOR (bare `php looper.php`): loops `checker.php --no-banner --fix --prod` every 60s — i.e. it
+  continuously AUTO-CORRECTS PRODUCTION** (prints a bold warning Mode line; the once-only LOOPER ASCII
+  banner gets the subline "Looper / Checker / Fixer" in fix-prod mode). `--no-fix` gives a **read-only
+  detect loop**. `--count 0` = forever; `--cmd` loops a verbatim command instead of checker (no flags
+  added); `--args` appends extra checker flags. Suppresses checker's own per-run banner; prints per-run
+  dividers with run #, timestamp, exit code, elapsed. Rationale: continuous unattended drift monitoring +
+  auto-correction.
 - `reconcile_netsuite_totals.php [from] [to] [--verbose]` — category grand totals NS vs Forecast2
   (Sales, Sales Profit, Open Orders, Opportunities) with deltas. Read-only. Connects explicitly to
   the **prod core2 reader**; NetSuite via SuiteQL SUMs. `--verbose` additionally prints the
@@ -141,6 +174,18 @@ by reconciling a chosen tranDate range directly against NetSuite.
   stays bounded under the existing 1G `memory_limit`. (This corrected a prior docblock claim that `$sqls`
   was never accumulated globally.)
 
+- **checker → fixer handoff is WINDOW-based, not id-based (decision).** checker hands fixer a tight day
+  window and lets fixer **re-find** the discrepant ids inside it, rather than passing exact ids. Rationale:
+  maker≠checker independence (fixer re-derives the drift), and checker has already shrunk the window, so a
+  re-scan is cheap. Id-passing only wins when drift is **sparse across a wide span** (it would skip fixer
+  re-scanning clean gaps). **Deferred (NOT built):** (a) an `--ids` skip-find path so checker passes exact
+  ids; (b) a `--since` "recency-pruned fingerprint" mode that uses NS `lastmodifieddate` to choose which
+  `trandate` buckets to fingerprint, walking backward until clean. ⚠ A `--since` mode has **structural blind
+  spots**: pure NS **deletions** (orphan Forecast rows) and **old untouched drift** are invisible to a
+  lastmodified scan, so the full `trandate` fingerprint stays the authoritative backstop. Forecast tables key
+  on `tranDate`, not NS `lastmodifieddate`, so a **symmetric** lastmodified fingerprint isn't possible — it
+  would require NS-pull-then-id-lookup or the recency-pruned approach.
+
 ## Data model
 
 `Forecast.Sales`, `Forecast.OpenOrderItems` on the **core2** cluster
@@ -206,6 +251,24 @@ None — Forecast2 is a single shared dataset.
   concentrated **Dec 2025–Apr 2026**, driven by NetSuite re-valuing `costestimate` on older
   invoices that no `lastmodifieddate`-based sync re-pulls. (Revenue reconciles to the penny; only
   profit drifts.)
+- **Open-orders "round-then-sum" vs "sum-then-round" — the most broadly reusable rounding gotcha.**
+  `Forecast.OpenOrderItems.revenue`/`profit` is `decimal(14,2)`: Forecast stores each open-order **LINE's**
+  revenue (`qtyOpen × rate`) **rounded to cents on store, then sums** (`SUM(round(line,2))`). A NetSuite-side
+  aggregate that does `ROUND(SUM(qtyOpen*rate),2)` (**sum-then-round**) diverges by up to ~½¢ **per line** —
+  benign rounding noise that **scales with line count**, so **no fixed aggregate-dollar tolerance can separate
+  it from real drift** (a busy bucket's benign band can reach whole dollars). This produced an **unfixable
+  phantom**: `fixer.php`'s FIND flags such a penny SO, but its FIX compares **per-line**, finds every line
+  already correct to the cent, writes nothing — and the SO churns forever in a loop. **FIX: round each line to
+  cents BEFORE summing on the NS side** — `SUM(ROUND(((-tl.quantity) - NVL(tl.quantitybilled,0)) * tl.rate, 2))`
+  — so NS matches Forecast's `decimal(14,2)` storage exactly; any remaining diff is then genuinely different
+  inputs = real drift. Applied to **both** `checker.php` (open-orders `nsSub` SELECT + HAVING) and `fixer.php`
+  `findOpenOrderDiscrepancies`. **Affects ONLY open orders** (a computed `qty×rate` product); Sales/Opportunities
+  sum pre-rounded `foreignamount`/`projectedtotal` and were already exact. Verified: full 18-month open-orders
+  window went from "drift" to cents-exact in sync after the fix. The previously-reported open-orders deltas were
+  entirely this artifact, NOT data drift: the ~$0.04 `reconcile` delta, and the per-SO 1¢ on **SO 6870666**
+  (NS 852.06 vs FC 852.07). **Correction to any prior note:** the open-orders **2025-04 "unlocalized month" was
+  this round-then-sum noise, NOT NS-live-vs-Forecast-replica timing jitter** — the rounding fix eliminated it,
+  disproving the earlier replica-jitter hypothesis.
 - **Compare money at 2 decimals.** DB columns store 2dp but PHP `revenue - cost` carries float
   dust (`313.6` vs `313.60000001`); raw `!=` produced thousands of phantom UPDATEs that re-wrote
   identical values (1,839 on one open-orders run). Both tools now compare `round((float)$x, 2)`.
@@ -297,6 +360,20 @@ None — Forecast2 is a single shared dataset.
 
 ## Change history
 
+- 2026-06-26 — **Added `checker.php` (moment-fingerprint drift detector) + `looper.php` (loop runner), and
+  found/fixed the open-orders round-then-sum rounding gotcha.** `checker.php` confirms sync in seconds and
+  localizes real drift via a 5-number per-bucket fingerprint (`n,rev,profit,idSum,idSq`; power-sums mod the
+  2³¹−1 prime → engine-portable) drilled top-down month→day→id, descending only into mismatched buckets,
+  pulling no rows on a clean book; hands fixer a tight **day window** (window handoff, not id — decision
+  recorded). `--fix` requires `--prod`; bare run never writes. `looper.php` defaults to looping
+  `checker --no-banner --fix --prod` every 60s (continuous prod auto-correction; `--no-fix` = read-only).
+  **Rounding gotcha:** `OpenOrderItems` `decimal(14,2)` stores each line round-then-sum, so a NS-side
+  sum-then-round aggregate diverges up to ~½¢/line (an unfixable phantom that loops fixer forever); fixed by
+  rounding each NS line to cents before summing (`SUM(ROUND(qtyOpen*rate,2))`) in both `checker.php` and
+  `fixer.php` `findOpenOrderDiscrepancies` — open-orders only (Sales/Opps already exact). This also
+  **disproves the earlier replica-jitter hypothesis** for the open-orders 2025-04 unlocalized month — it was
+  the same per-line rounding. Deferred: `--ids` skip-find and a `--since` recency-pruned fingerprint (blind to
+  NS deletions + old untouched drift). (dfranks)
 - 2026-06-25 — **`trueup_open_orders` Step 4 now lists the exact per-statement SQL** (`<NS SO id>  <SQL>`,
   one line per statement) for both live and `--dry-run` passes, so a dry-run is auditable and any
   unexpected insert/update/delete is traceable to its source order. Implemented via a global `$sqlLog`

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.220",
+  "version": "1.0.222",
   "description": "TOGA Technology Team Claude Knowledge System — shared AI coding harness with skills, knowledge base CLI, and project installer for Claude Code.",
   "keywords": [
     "claude",