toga-ai 1.0.97 → 1.0.99

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

@@ -5,3 +5,4 @@
 | [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 |
 | [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/analyze_netsuite_forecast_diff.php, test/@dave/trueup_sales.php, test/@dave/trueup_open_orders.php, test/@dave/trueup_opportunities.php, test/@dave/probe_sales_gap_direct.php, worker/crons/toga2/forecast2/common_import_sales_from_netsuite.php |
 | [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/architecture.md

@@ -37,6 +37,11 @@ which **self-elects a distinct role** (`notification`, `database`, `infrastructu
 > than run inside a web request. It builds on the `library` core (see
 > [Library architecture](../library/architecture.md)).
 
+**Critical rules:** all classes use the `App_` prefix (1.0 framework). CRON scripts are plain PHP
+under `crons/`; the schedule (cron registration) is the source of truth for what runs — a script
+that isn't scheduled never executes. Client integrations live under `crons/toga2/<client>/`.
+Use prepared statements for all SQL; never interpolate input.
+
 ## How a job becomes a cron (the dispatch pipeline)
 
 There is **no in-process scheduler**. Jobs are plain PHP files invoked by the OS `crontab`,

package/knowledge/1.0/apps/worker/workflows/onboarding-client-to-netsuite-togasupply-sync.md

@@ -0,0 +1,116 @@
+---
+title: Onboarding a Client to the NetSuite TOGa Supply Sync
+framework: "1.0"
+repo: worker
+project: Worker
+client: shared
+type: workflow
+status: active
+updated: 2026-06-16
+owners: ["dfranks"]
+files:
+  - 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
+related: []
+---
+
+## Summary
+How to add a new TOGa 2 client to the per-client NetSuite → TOGa Supply importer
+(`worker/crons/toga2/netsuite/`). Each client gets a thin wrapper cron that sets its
+`CLIENT_CONFIGURATION` + `IS_ENABLED_*` flags and then `require_once`s the shared
+`common_sync_togasupply.php`, which builds all lookups and runs the 6 sync sections
+(Sales Orders, Purchase Orders, Invoices, Item Receipts, Item Fulfillments, Inventory
+Adjustments). Reads come from production NetSuite (REST/SuiteQL); writes go to the TOGa2
+API (`App_Api_Toga2::send`), which lands in that client's `Client_<Name>` database.
+
+## Steps
+1. **Create the wrapper** `worker/crons/toga2/netsuite/sync_togasupply_<client>.php`,
+   modeled exactly on an existing one (e.g. `sync_togasupply_compass_usa.php`). Set
+   `CLIENT_CONFIGURATION` (`client`, `isParentCustomer`, `api`, `secret`,
+   `importCustomerPurchaseOrdersOnVendor`) and the constants. Shared constants are the same
+   across clients: `NETSUITE_CUSTOM_FIELD_ID__END_USER_CUSTOMER = 3149`,
+   `SHIPPING_LOCATION_TYPE_UUID = 527a3995-…`, `WAREHOUSE_LOCATION_TYPE_UUID = 78c24f51-…`,
+   and `importCustomerPurchaseOrdersOnVendor = 10ed18ec-0999-53d9-f9db-5892d90f09d4`.
+   Get `client` from `Core.Clients` (by name); get `api`/`secret` from
+   `Client_<Name>.Apis`. Lint with `C:\xampp7\php\php.exe -l` (prod is PHP 7.2).
+2. **Determine `isParentCustomer` by probing NetSuite — do not assume.** It controls whether
+   the common body calls `listChildCustomers()` (parent) or `fetchCustomerById()` (flat).
+   `listChildCustomers(N)` runs `SELECT id FROM customer WHERE parent = N`. If the client's
+   NetSuite customer has **zero children**, `isParentCustomer` MUST be `false`, or the sync
+   builds an empty customer list, registers nothing, and imports nothing (silent no-op). See
+   Gotchas.
+3. **Seed the Parameters table** (see the dedicated section below) — REQUIRED or the sync
+   aborts on its first parameter read.
+4. **Add the schedule entry** in `worker/schedules/cron.worker.sync.json`: all
+   `sync_togasupply_*` jobs run `*/5 * * * *`, `active: 1`. The cron only runs once a
+   schedule entry references the file and the worker is redeployed.
+5. **Deploy order matters:** the Parameters seed must hit prod `Client_<Name>` **before or
+   with** the cron going live, or the sync 404-aborts (and throws a Sentry error) every 5
+   minutes.
+
+## Parameters seed (the required, easily-missed step)
+The sync reads/writes per-client sync state via the TOGa2 API `/parameters` endpoint, which
+is **update-only** — a `GET`/`PUT` on a non-existent key returns `404 EV-6`, and because
+`App_Api_Toga2::send()` defaults `$throwExceptionOnApiError = true`, that 404 **throws and
+aborts the entire run** before any record is processed. The `startModeIteration()` ternary
+(`isSuccess ? value : MIN_DATETIME`) looks like it tolerates a missing key, but it never
+gets there because `send()` throws first. Every live client (e.g. Compass) was seeded at
+onboarding; a new client has none.
+
+The `Parameters` *table* already exists in every `Client_<Name>` DB — you only seed **rows**.
+Add a `dbchanges2/Client_<Name>/<date> - NetsuiteSyncParameters.sql` migration modeled on
+`dbchanges2/_modules/netsuite/2026-04-01 - Parameters.sql`, inserting all **12** keys:
+- 6 × `NETSUITE_LAST_SYNC_DATETIME_{SALES_ORDERS,PURCHASE_ORDERS,INVOICES,ITEM_RECEIPTS,ITEM_FULFILLMENTS,INVENTORY_ADJUSTMENTS}`
+  → a start datetime. This sets how far back the initial backfill pulls (5-day windows, every
+  5 min). Pick deliberately: `2018-01-01` = full history; a recent date = go-forward only.
+- 6 × `NETSUITE_EXECUTION_MODE_*` → `864000-IDLE` (the interval is clamped to
+  `MAX_TIME_WINDOW_TO_FETCH_FROM_NETSUITE_SECONDS = 432000` on first run, so the exact
+  seed interval is not critical; `IDLE` is what matters).
+
+Use `(UUID(), '<key>', '<value>')` rows — `Parameters.uuid` is required and unique.
+dbchanges2 files use the unqualified `Parameters` table name (deployer selects the DB from
+the directory; no `USE`).
+
+## Systems involved
+- `worker` cron tier (1.0) — the wrapper + `common_sync_togasupply.php`.
+- Production NetSuite (account `1095849`) via `App_Api_Netsuite_Rest` (SuiteQL/REST) — reads.
+- TOGa2 API (`App_Api_Toga2`) — writes to `Client_<Name>` (+ logs to `Logs_<Name>`).
+- `dbchanges2/Client_<Name>/` — the Parameters seed migration.
+
+## Local testing
+- The worker's `[api] _` and api2's `[database]/[databaseClient]/[database1]` on the dev
+  laptop point at local (`http://api2/v2` → local Apache/api2 → localhost MySQL). NetSuite is
+  the **production** account but reads are read-only.
+- A local end-to-end run needs the client's schemas present locally: import both
+  `Client_<Name>` AND `Logs_<Name>` from the read replicas (client2 / logs clusters) into
+  local XAMPP. `Logs_<Name>` only needs the **schema** (`mysqldump --no-data`) — its API-log
+  history can be many GB; api2 connects to it (link `ClientLogs`) on every request and 500s
+  with "Unknown database 'logs_<name>'" if absent.
+- Run the cron in place with `C:\xampp8\php\php.exe` from the `worker/` dir; the autoloader
+  walks up to `worker/_` for `__APPROOT__`. `App_Api_Netsuite_Rest::authenticate()` +
+  `App_ApiTransaction->setLogging(false)` is the laptop-safe NetSuite pattern (see
+  `test/@dave/nsq.php`, a read-only SuiteQL runner).
+- Verified behavior: empty window → 0 writes, checkpoint advances (clean no-op); record
+  already present → `PUT` update (idempotent, keyed on `c_netsuiteInternalSalesOrderId`, no
+  dupes); record absent → `POST` insert. Checkpoints (`NETSUITE_LAST_SYNC_DATETIME_*`)
+  advance by one window and `NETSUITE_EXECUTION_MODE_*` flips back to `…-IDLE` when a section
+  finishes cleanly.
+
+## Edge cases & escalation
+- **`isParentCustomer` wrong** → silent no-op (true on a childless customer) or missed
+  end-user matching. Always probe NetSuite first.
+- **Parameters not seeded in prod** → sync throws every 5 min; surfaces as a `worker1` Sentry
+  error and zero imports.
+- **Missing catalog item** on an incoming order may throw mid-run depending on the section;
+  the checkpoint does not advance past a throwing window, so it self-heals once the dependency
+  exists.
+
+## Change history
+- 2026-06-16 — Documented the onboarding process after adding Quad (TRUE-79575): wrapper +
+  schedule + the required 12-key Parameters seed; captured the `isParentCustomer` NetSuite
+  probe and the local Client_/Logs_ schema requirement. (dfranks)
+
+## Related docs
+- [Forecast2 NetSuite reconciliation](../features/forecast2-netsuite-reconciliation.md)

package/{rules/php/app-framework.md → knowledge/1.0/standards/framework-rules.md}

@@ -1,6 +1,23 @@
+---
+title: "Framework 1.0 (App_) Rules"
+framework: "1.0"
+project: Library
+client: shared
+type: standard
+status: active
+updated: 2026-06-16
+owners: [jcardinal]
+files: []
+related:
+  - ../apps/library/architecture.md
+  - ../apps/worker/architecture.md
+---
+
 # Framework 1.0 (App_) Rules
 
-These rules apply to all repos under `C:\WWW\1.0`: `library` (core) and `worker` (app).
+These rules apply to all 1.0 repos: `library` (core) and `worker` (app). They are loaded
+on-demand by `/kickoff` when a 1.0 repo is in scope (not always-on) — see the rules-scoping
+note in `CONVENTIONS.md`.
 
 ## Class naming
 

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

@@ -28,6 +28,11 @@ configuration, ACL, and third-party integrations. Every 2.0 project depends on i
 Minimum PHP 8.1 (enforced in `_underscore.php`). The current architecture is
 **decoupled**: React handles the frontend; `_underscore` serves as the backend API layer.
 
+**Critical rules:** framework classes use a leading-underscore prefix (`_Model_*`, `_Controller_*`,
+`_Worker_*`). Always use parameterized queries / the `_Db` layer — never interpolate input into SQL.
+Beware the **lazy-transaction gotcha**: writes issued outside an explicitly committed transaction
+can be silently dropped — confirm commit semantics before relying on a write.
+
 ## Entry point & boot sequence
 
 Every 2.0 project's `index.php` is just `<?php require '_underscore.php';`.

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

@@ -31,6 +31,10 @@ Runtime: PHP 8.2+, AWS Elastic Beanstalk (Apache/httpd → PHP-FPM). The `_under
 framework is **pulled at deploy, not vendored**. Composer deps: `sentry/sentry`,
 `aws/aws-sdk-php`, `robrichards/xmlseclibs`, `phpmailer/phpmailer`.
 
+**Critical rules:** every action method must return the exact envelope
+`['success' => bool, 'data' => mixed, 'errors' => array]` — never a raw string or bare array.
+On error: `success=false`, `data=null`, `errors=[...]`. Deviating breaks API consumers silently.
+
 ## Dependencies
 
 - **`_underscore` (framework core)** — this API is essentially a metadata-driven layer over

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

@@ -33,6 +33,11 @@ Because execution order is purely alphabetical, **file naming is the contract.**
 named with a leading **`YYYY-MM-DD`** date so alphabetical sort = chronological order, which
 is the intended execution order.
 
+**Critical rules:** every new `.sql` file **must** be named `YYYY-MM-DD<letter> - <Description>.sql`
+with a **mandatory lower-case letter** right after the date (`a` for the first file of that day
+in a folder, then `b`, `c`, …). One folder per database; place client changes under the matching
+`Client_<Name>` folder. Never edit an already-run migration — add a new dated file instead.
+
 ## File naming convention (the execution contract)
 
 1. **Date prefix, ISO format:** every file starts `YYYY-MM-DD`. ISO ordering means

package/{rules/php/underscore-framework.md → knowledge/2.0/standards/framework-rules.md}

@@ -1,6 +1,24 @@
+---
+title: "Framework 2.0 (_underscore) Rules"
+framework: "2.0"
+project: _Underscore
+client: shared
+type: standard
+status: active
+updated: 2026-06-16
+owners: [jcardinal]
+files: []
+related:
+  - ../apps/_underscore/architecture.md
+  - ../apps/worker2/architecture.md
+  - ../apps/api2/architecture.md
+---
+
 # Framework 2.0 (_underscore) Rules
 
-These rules apply to all repos under `C:\WWW\2.0`: `_underscore` (core), `worker2` (app), and `api2` (app).
+These rules apply to all 2.0 repos: `_underscore` (core), `worker2`, and `api2`. They are
+loaded on-demand by `/kickoff` when a 2.0 repo is in scope (not always-on) — see the
+rules-scoping note in `CONVENTIONS.md`.
 
 ## Class naming
 

package/{rules/python → knowledge/2.0/standards}/python.md

@@ -1,8 +1,24 @@
+---
+title: "Python Rules"
+framework: "2.0"
+project: Talos
+client: shared
+type: standard
+status: active
+updated: 2026-06-16
+owners: [jcardinal]
+files: []
+related:
+  - ../apps/talos/architecture.md
+  - ../apps/voice-to-voice/architecture.md
+---
+
 # Python Rules (applies to all TOGA Python repos)
 
 Applies to every TOGA Python project: **talos** (`aegra-api`, `react_agent`,
-`mcp-servers/*`) and **voice-to-voice** (`core/`, `clients/*`,
-`lambda_updated/`). Future Python repos inherit these by default.
+`mcp-servers/*`) and **voice-to-voice** (`core/`, `clients/*`, `lambda_updated/`). Future
+Python repos inherit these by default. Loaded on-demand by `/kickoff` only when a Python repo
+(registry `language: python`) is in scope — see the rules-scoping note in `CONVENTIONS.md`.
 
 ## Toolchain
 

package/knowledge/CONVENTIONS.md

@@ -168,6 +168,37 @@ those three doc types fails the build (and therefore blocks `capture`'s publish)
 `architecture`, and `standard` docs are exempt. Keep the list terse and cap it at ~10 entries,
 folding older ones away.
 
+## Rules scoping (universal always-on vs framework on-demand)
+
+`rules/` carries only **universal** always-on rules (security, coding-style, git-workflow,
+testing) — installed to `.claude/rules/toga/common/` and loaded every session.
+
+**Framework-specific** rules live in the knowledge base as `type: standard` docs and load
+**on-demand via `/kickoff`** for the framework in scope:
+
+- `knowledge/1.0/standards/framework-rules.md` — 1.0 `App_` conventions (loads when a 1.0 repo is chosen)
+- `knowledge/2.0/standards/framework-rules.md` — 2.0 `_underscore` conventions (loads when a 2.0 repo is chosen)
+- `knowledge/2.0/standards/python.md` — Python rules (loads only when a repo with registry
+  `language: python` — e.g. `talos`, `voice-to-voice` — is in scope)
+
+`kickoff-preflight` emits these in its `standards` list; kickoff reads them like any other
+standard. This keeps a session from carrying rules for a framework it isn't working in. When
+adding a Python repo, set `"language": "python"` on its `registry.json` entry so its rules load.
+
+## Architecture `## Summary` — must carry "Critical rules"
+
+Every `architecture.md` opens with a `## Summary` section. Kickoff loads this summary (not the
+full doc) for any repo pulled in as **awareness only** — e.g. a client-app the developer didn't
+explicitly name (see [Client app-scope](#client-app-scope-apps-on-profilemd)). So the summary is
+often the *only* thing a session sees for that repo.
+
+Therefore each `## Summary` must end with a **`**Critical rules:**`** line capturing the few
+load-bearing, must-not-violate rules for that repo — the things that would cause a real defect if
+missed even when the full doc is never opened. Examples: dbchanges2's mandatory `YYYY-MM-DD<letter>`
+filename suffix; api2's exact `{success,data,errors}` response envelope; `_underscore`'s
+lazy-transaction write-drop gotcha. Keep it to 2–4 sentences. This is what lets summaries stay cheap
+without losing safety.
+
 ## INDEX.md files
 
 Never hand-edited. `node knowledge.js index` regenerates the master `INDEX.md`, each

package/knowledge/INDEX.md

@@ -5,7 +5,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 ## 1.0 framework
 
 - **library** (Library) _(framework core)_ — 4 doc(s) → [1.0/apps/library/INDEX.md](1.0/apps/library/INDEX.md)
-- **worker** (Worker) — 4 doc(s) → [1.0/apps/worker/INDEX.md](1.0/apps/worker/INDEX.md)
+- **worker** (Worker) — 5 doc(s) → [1.0/apps/worker/INDEX.md](1.0/apps/worker/INDEX.md)
 - **togadesk** (TOGa Desk) — 7 doc(s) → [1.0/apps/togadesk/INDEX.md](1.0/apps/togadesk/INDEX.md)
 - **togaview** (TOGa View) — 5 doc(s) → [1.0/apps/togaview/INDEX.md](1.0/apps/togaview/INDEX.md)
 - **webhook** (Webhook) — 1 doc(s) → [1.0/apps/webhook/INDEX.md](1.0/apps/webhook/INDEX.md)

package/knowledge/registry.json

@@ -14,8 +14,8 @@
   { "repo": "togatech",    "project": "TOGA Technology Website", "framework": "standalone", "role": "app", "dependsOn": [] },
   { "repo": "webhook",     "project": "Webhook",     "framework": "1.0", "role": "app",  "dependsOn": ["library"] },
   { "repo": "walmarttechservices", "project": "Walmart Tech Services", "framework": "1.0", "role": "app", "dependsOn": ["library"] },
-  { "repo": "talos",       "project": "TOGa IQ",      "framework": "2.0", "role": "app", "dependsOn": [] },
+  { "repo": "talos",       "project": "TOGa IQ",      "framework": "2.0", "role": "app", "dependsOn": [], "language": "python" },
   { "repo": "test",        "project": "Test",        "framework": "1.0", "role": "app",  "dependsOn": ["library"] },
-  { "repo": "voice-to-voice", "project": "TOGa Voice", "framework": "2.0", "role": "app", "dependsOn": [] },
+  { "repo": "voice-to-voice", "project": "TOGa Voice", "framework": "2.0", "role": "app", "dependsOn": [], "language": "python" },
   { "repo": "ai-bdr",      "project": "AI-BDR",      "framework": "2.0", "role": "app", "dependsOn": [] }
 ]

package/knowledge.js

@@ -213,22 +213,34 @@ function cmdPreflight(args) {
             clientApps = (Array.isArray(data.apps) ? data.apps : []).filter(r => registry.find(x => x.repo === r));
         }
     }
-    const chosen = [...new Set([...devChosen, ...clientApps])];
-    if (!chosen.length) {
+    // Dev-named repos load FULL (deep work). Client apps load as SUMMARIES only
+    // (awareness) unless the dev also explicitly named them — this keeps a client
+    // kickoff cheap: a teammate who only mentions "Compass" gets a one-paragraph
+    // summary of every client app (incl. its critical rules) without paying the
+    // full-architecture cost of repos they aren't touching. (P1)
+    const chosen = [...new Set(devChosen)];
+    const scope = [...new Set([...chosen, ...clientApps])]; // full ∪ awareness
+    if (!scope.length) {
         console.log(JSON.stringify({ error: 'PREFLIGHT: provide --repos=<repo,repo> and/or --client=<slug> whose profile lists apps' }));
         process.exitCode = 1;
         return;
     }
     const layer = String(args.layer || 'hybrid').toLowerCase();
     const q = args.q ? String(args.q).toLowerCase() : null;
-    const unknown = chosen.filter(r => !registry.find(x => x.repo === r));
+    const unknown = scope.filter(r => !registry.find(x => x.repo === r));
 
-    // frameworks involved (from the chosen repos)
+    // Standards load per framework the dev is ACTUALLY working in (chosen). If the
+    // dev named nothing (client-only kickoff), fall back to every in-scope framework.
     const fwSet = new Set();
-    for (const r of chosen) { const e = registry.find(x => x.repo === r); if (e) fwSet.add(e.framework); }
+    const fwSource = chosen.length ? chosen : scope;
+    for (const r of fwSource) { const e = registry.find(x => x.repo === r); if (e) fwSet.add(e.framework); }
     const frameworks = [...fwSet];
 
-    // dependency load-set: framework core(s) first, then transitive dependsOn, then chosen
+    // dependency load-set: framework core(s) first, then transitive dependsOn, then
+    // everything in scope (chosen full + client-app awareness, both as load-set entries;
+    // only `chosen` get full reads below — the rest are summarized).
+    const scopeFwSet = new Set();
+    for (const r of scope) { const e = registry.find(x => x.repo === r); if (e) scopeFwSet.add(e.framework); }
     const seen = new Set();
     const loadSet = [];
     const visit = (r) => {
@@ -237,8 +249,8 @@ function cmdPreflight(args) {
         for (const d of (e.dependsOn || [])) visit(d);
         if (!seen.has(r)) { seen.add(r); loadSet.push(r); }
     };
-    for (const fw of frameworks) for (const core of coreReposFor(registry, fw)) visit(core);
-    for (const r of chosen) visit(r);
+    for (const fw of scopeFwSet) for (const core of coreReposFor(registry, fw)) visit(core);
+    for (const r of scope) visit(r);
 
     const docs = allDocs();
     const chosenSet = new Set(chosen);
@@ -277,6 +289,21 @@ function cmdPreflight(args) {
     for (const fw of frameworks) {
         if (wantBackend) standards.push({ ...fileInfo(`${fw}/standards/backend-php.md`), framework: fw });
         if (wantFrontend) standards.push({ ...fileInfo(`${fw}/standards/frontend.md`), framework: fw });
+        // Framework-specific convention rules (App_ / _underscore). These used to load
+        // always-on for every session; they now ride with the framework's standards so a
+        // session only carries the rules for the framework it is actually working in. (P2)
+        if (wantBackend) {
+            const fr = fileInfo(`${fw}/standards/framework-rules.md`);
+            if (fr.exists) standards.push({ ...fr, framework: fw });
+        }
+    }
+    // Python rules load only when a Python repo (registry `language: python`) is in scope —
+    // not for every 2.0 PHP session. (P2)
+    const pythonRepos = scope.filter(r => { const e = registry.find(x => x.repo === r); return e && e.language === 'python'; });
+    if (wantBackend && pythonRepos.length) {
+        const pe = registry.find(x => x.repo === pythonRepos[0]);
+        const py = fileInfo(`${pe.framework}/standards/python.md`);
+        if (py.exists) standards.push({ ...py, framework: pe.framework, language: 'python' });
     }
 
     // client docs (profile + features/workflows filtered to involved frameworks)
@@ -324,7 +351,28 @@ function cmdPreflight(args) {
     // profile.md `apps:` (vs. named by the developer) so it can show "loaded because you
     // mentioned <client>" and the dev can still add/remove.
     const clientScope = { client: slug, fromClient: clientApps, fromDev: devChosen };
-    console.log(JSON.stringify({ frameworks, loadSet, unknown, clientScope, repos: repoOut, standards, client, reads }));
+
+    // Load-size estimate (P6): rough word/token cost of everything kickoff will read,
+    // so the skill can warn when a scope is unusually heavy (e.g. too many full repos)
+    // and the dev can narrow `--repos`. Full reads count the doc body; lazy summaries
+    // count only the inlined summary text. ~1.3 tokens/word is a coarse heuristic.
+    const wc = s => (String(s || '').trim().match(/\S+/g) || []).length;
+    const docByRel = new Map(docs.map(d => [d.rel, d]));
+    let fullWords = 0, summaryWords = 0;
+    for (const r of reads) {
+        if (!r.exists) continue;
+        if (r.lazy) { summaryWords += wc(r.summary); continue; }
+        const d = docByRel.get(r.path);
+        if (d) fullWords += wc(d.body);
+    }
+    const words = fullWords + summaryWords;
+    const estimate = {
+        words, tokensApprox: Math.round(words * 1.3),
+        fullReads: reads.filter(r => r.exists && !r.lazy).length,
+        summaries: reads.filter(r => r.exists && r.lazy).length,
+        heavy: words > 8000, // kickoff should suggest narrowing --repos above this
+    };
+    console.log(JSON.stringify({ frameworks, loadSet, unknown, clientScope, estimate, repos: repoOut, standards, client, reads }));
 }
 
 /* ------------------------------------------------------------------ */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toga-ai",
-  "version": "1.0.97",
+  "version": "1.0.99",
   "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/rules/README.md

@@ -1,26 +1,34 @@
 # Rules Directory
 
-Rules are **always-follow guidelines** that are loaded automatically into every Claude Code session. Unlike skills (which are on-demand slash commands), rules are passive context — Claude reads them and applies them without being asked.
+Rules here are the **universal, always-on guidelines** loaded automatically into every Claude Code session. Unlike skills (on-demand slash commands), rules are passive context — Claude reads them and applies them without being asked.
+
+> **Scoping (P2):** only **universal** rules live here and load always-on. **Framework-specific**
+> rules (1.0 `App_`, 2.0 `_underscore`, Python) were moved into the knowledge base under
+> `knowledge/<fw>/standards/framework-rules.md` (and `2.0/standards/python.md`) and are loaded
+> **on-demand by `/kickoff`** for the framework actually in scope. This keeps every session from
+> carrying rules for frameworks it isn't touching. See `knowledge/CONVENTIONS.md`.
 
 ## What belongs here
 
-Rules files contain direct imperatives: coding style, security requirements, git workflow, framework conventions. They do not contain architecture documentation (that goes in `knowledge/`) or how-to instructions (that goes in `skills/`).
+Only **language- and framework-agnostic** imperatives: coding style, security, git workflow,
+testing. Framework-specific conventions belong in `knowledge/<fw>/standards/`. Architecture
+documentation goes in `knowledge/`; how-to instructions go in `skills/`.
 
 ## Directory structure
 
 ```
 rules/
-├── README.md                    ← this file
-├── common/                      ← apply to all repos and both frameworks
-│   ├── coding-style.md          ← language-agnostic style rules
-│   ├── git-workflow.md          ← branching, commit messages, PR rules
-│   ├── security.md              ← security rules (critical — always followed)
-│   └── testing.md               ← test requirements
-└── php/                         ← PHP-specific rules
-    ├── app-framework.md         ← 1.0 App_ framework rules
-    └── underscore-framework.md  ← 2.0 _underscore framework rules
+├── README.md                    ← this file (not installed)
+└── common/                      ← UNIVERSAL — apply to all repos, all frameworks (always-on)
+    ├── coding-style.md          ← language-agnostic style rules
+    ├── git-workflow.md          ← branching, commit messages, PR rules
+    ├── security.md              ← security rules (critical — always followed)
+    └── testing.md               ← test requirements
 ```
 
+Framework-specific rules are NOT here — see `knowledge/1.0/standards/framework-rules.md`,
+`knowledge/2.0/standards/framework-rules.md`, and `knowledge/2.0/standards/python.md`.
+
 ## How to install
 
 Run from the team knowledge repo root:
@@ -29,7 +37,8 @@ Run from the team knowledge repo root:
 node scripts/install.js
 ```
 
-This copies all files from `rules/` into `.claude/rules/toga/` in the target project. Claude Code automatically loads rules from `.claude/rules/`.
+This copies `rules/common/` into `.claude/rules/toga/common/` in the target project (and prunes
+any stale pre-P2 framework rules). Claude Code automatically loads rules from `.claude/rules/`.
 
 If you want to install into a specific project:
 
@@ -39,7 +48,8 @@ node scripts/install.js /path/to/project
 
 ## How to add new rules
 
-1. Create a new `.md` file in the appropriate subdirectory (`common/` or `php/`).
+1. Universal rule? Add a `.md` under `common/`. Framework-specific? Add it to the matching
+   `knowledge/<fw>/standards/framework-rules.md` (or `python.md`) instead — do not put it here.
 2. Write direct imperatives — "Never do X", "Always do Y". No meta-commentary.
 3. Keep each file under 200 lines.
 4. Run `node scripts/install.js` to push the new rule to all installed projects.

package/scripts/install.js

@@ -411,37 +411,17 @@ If you close without running /capture, the knowledge is lost.
 
 ---
 
-### Available Skills (slash commands)
+### Skills & agents
 
-${skillNames.map((s) => `- \`/${s}\``).join('\n')}
+Your Claude Code session already lists every available \`/skill\` and specialist agent on each
+launch — this file intentionally does **not** duplicate that catalog (a static copy only drifts
+out of date). The rules that matter:
 
----
-
-### Agents (Claude spawns these automatically — you can also invoke them explicitly)
-
-Each agent is a specialist. Claude delegates to them when the task fits. You can
-also tell Claude "use the php-reviewer agent on this file" explicitly.
-
-| Agent | When it activates |
-|---|---|
-| **php-reviewer** | Any PHP file is written or edited |
-| **sql-reviewer** | SQL queries detected in PHP or migration files |
-| **framework-pattern-checker** | New PHP class created — validates App_ vs _underscore conventions |
-| **php-build-resolver** | PHP fatal error or parse error in output |
-| **planner** | New feature request — produces phased implementation plan |
-| **knowledge-writer** | You ask Claude to document something — writes correct frontmatter |
-| **session-capture** | Runs inside /capture — extracts and categorizes session learnings |
-| **harness-optimizer** | Run /harness-audit — scores and improves this harness setup |
-
-**Multi-agent workflow example:**
-When you say "build the order refund endpoint", Claude will:
-1. Spawn **planner** → get phased implementation plan
-2. Write code → **framework-pattern-checker** validates conventions automatically
-3. Write SQL → **sql-reviewer** checks for injection and N+1 patterns
-4. After editing PHP → **php-reviewer** runs security and style checks
-5. At /capture → **session-capture** extracts decisions for the knowledge base
-
-You do not need to manage this manually. The agents are wired to the right triggers.
+- **\`/kickoff\` first, \`/capture\` last** — every session (see above).
+- Specialist agents (php-reviewer, sql-reviewer, framework-pattern-checker, planner,
+  knowledge-writer, session-capture, php-build-resolver, harness-optimizer) fire **automatically**
+  on the matching file or operation. You can also invoke one explicitly — e.g. "use the
+  php-reviewer agent on this file."
 
 ---
 
@@ -629,14 +609,24 @@ function main() {
   }
   console.log('  ✓ Skills    (' + skillNames.length + '): ' + fmtStats(skillStats));
 
-  // Rules — update if content changed (team standards should always be current)
-  const rulesSrc = path.join(harnessDir, 'rules');
-  const rulesDest = path.join(claudeDir, 'rules', 'toga');
+  // Rules — only the UNIVERSAL set (rules/common) installs always-on. Framework-specific
+  // rules (1.0 App_, 2.0 _underscore, Python) now live in the knowledge base under
+  // <fw>/standards/ and load on-demand via /kickoff per the framework in scope (P2), so a
+  // session never carries rules for a framework it isn't working in.
+  const rulesToga = path.join(claudeDir, 'rules', 'toga');
+  const rulesSrc = path.join(harnessDir, 'rules', 'common');
+  const rulesDest = path.join(rulesToga, 'common');
   let rulesStats = { added: 0, updated: 0, unchanged: 0 };
   if (fs.existsSync(rulesSrc)) {
     try { rulesStats = copyDir(rulesSrc, rulesDest, { updateIfChanged: true }); }
     catch (e) { errors.push('rules: ' + e.message); }
   }
+  // Prune framework-specific rules + the meta README left behind by pre-P2 installs so
+  // they stop loading always-on (their content now lives in <fw>/standards/).
+  for (const stale of ['php', 'python', 'README.md']) {
+    const p = path.join(rulesToga, stale);
+    try { if (fs.existsSync(p)) fs.rmSync(p, { recursive: true, force: true }); } catch (_) { /* best-effort cleanup */ }
+  }
   console.log('  ✓ Rules     (' + countMd(rulesDest) + '): ' + fmtStats(rulesStats));
 
   // Agents — update if content changed

package/skills/capture/SKILL.md

@@ -343,6 +343,13 @@ related: []
 ---
 
 ## Summary
+<2–4 sentence overview of the repo. **End the Summary with a `**Critical rules:**` line** — the
+few load-bearing must-knows that have to ride along when only this summary is loaded (kickoff
+loads the Summary, not the full doc, for repos pulled in as client-app awareness). See
+`CONVENTIONS.md` → *Architecture Summary*. Examples: dbchanges2's mandatory `YYYY-MM-DD<letter>`
+filename suffix; api2's exact `{success,data,errors}` envelope; `_underscore`'s lazy-transaction
+write-drop gotcha.>
+
 ## <system sections: components, data, flows, key decisions>
 ```
 

package/skills/kickoff/SKILL.md

@@ -35,16 +35,13 @@ description: Start-of-session context loader for TOGA Technology projects. Run t
 
 ## Arguments — text passed after `/kickoff` never skips any step
 
-`/kickoff` may be invoked with trailing text (e.g. `/kickoff worker2 backend fix for Compass`),
-including a long, specific paragraph naming exact files, line numbers, and a concrete
-change. That text is the developer's description of today's work — it is **not** permission
-to shortcut the flow, no matter how actionable it looks.
+Trailing text (e.g. `/kickoff worker2 backend fix for Compass`, even a detailed paragraph
+naming files and line numbers) is the developer's description of today's work — **input to the
+Step 2 interview, not permission to shortcut the flow** (the STOP gate above governs this).
 
 - **Step 0 (auto-update check) ALWAYS runs first**, with or without arguments.
-- Use the argument text to **pre-fill answers** to the Step 2 interview (framework, layer,
-  repo, client, task). Only ask about whatever is still missing or ambiguous.
-- Never treat the argument as an instruction to start coding — or even to start *reading
-  the named files* — before Steps 0–6 complete. Investigation IS work; it waits for priming.
+- Use the argument text to **pre-fill** Step 2 answers (framework, layer, repo, client, task);
+  ask only about what's still missing or ambiguous.
 
 ## Step 0 — Auto-update check (runs before anything else, even with arguments)
 
@@ -247,6 +244,14 @@ Tell the developer concisely:
   say so explicitly: "No knowledge captured yet for X — `capture` will build it as you work."
 - Confirm you're primed and ready for their first task.
 
+**Heavy-load check (from preflight `estimate`).** Preflight returns
+`estimate {words, tokensApprox, fullReads, summaries, heavy}`. If `estimate.heavy` is true
+(load > ~8k words — usually too many full repos), tell the developer and suggest narrowing:
+> "This scope loads ~`tokensApprox` tokens across `fullReads` full repos. If you're only
+> touching one, name just that repo (`also drop <repo>`) so the rest stay as summaries."
+Client `apps` load as cheap summaries by default, so a large client rarely trips this — it's
+usually too many repos passed to `--repos`.
+
 ## New-repo onboarding (when the developer names a repo not in `registry.json`)
 
 Ask **all** of the following — assume nothing (you may offer a suggested default, e.g.