toga-ai 1.0.23 → 1.0.25

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

@@ -6,7 +6,7 @@ project: _Underscore
 client: shared
 type: architecture
 status: active
-updated: 2026-06-08
+updated: 2026-06-09
 owners: [jcardinal]
 files:
   - _underscore/_underscore.php
@@ -73,6 +73,98 @@ multi-tenant client-DB lookup from Core. `Query.php` wraps MySQLi with read/writ
 auto-routing and result helpers: `fetchRows()`, `fetchRow()`, `fetchOne()`,
 `fetchRowsAssocArray()`, `fetchKeyValuePairs()`, `fetchValues()`.
 
+### Physical infrastructure
+
+Each **environment** is one or more MySQL clusters. Every cluster has a single
+**writer** host and three **reader** hosts, one per AWS region. The framework routes
+reads to the reader nearest the request's origin and sends all writes to the writer:
+
+| Region constant | AWS region | Reader role |
+|---|---|---|
+| region 1 | `us-east-1` | `reader1.*` |
+| region 2 | `us-west-2` | `reader2.*` |
+| region 3 | `eu-west-1` | `reader3.*` |
+
+#### Production clusters
+
+Production (`prod` / `production`) splits its databases across **four dedicated
+clusters** by database family. Each has a writer + three regional readers under its own
+DNS subdomain (`*.<family>.database.togahub.com`):
+
+| Cluster | Schema group | Databases served | DNS host pattern |
+|---|---|---|---|
+| `prod-core` | platform | `Core`, `Forecast`, `Forecast_Archive`, `Team` | `writer.core…` / `reader{1,2,3}.core.database.togahub.com` |
+| `prod-client` | tenants | `Client_<Tenant>` (active client data) | `writer.client…` / `reader{1,2,3}.client.database.togahub.com` |
+| `prod-archive` | archive | `Archive_<Tenant>` (historical subset of `Client_`) | `writer.archive…` / `reader{1,2,3}.archive.database.togahub.com` |
+| `prod-logs` | tenant_logs | `Logs_<Tenant>` + base `Logs` | `writer.logs…` / `reader{1,2,3}.logs.database.togahub.com` |
+
+**`Core` is the most important database** — it holds the common tables shared across
+the whole platform (clients, domains, environments, ACL, parameters, APIs, records,
+record scripts, payload interceptors).
+
+#### Database families & tenant resolution
+
+Within an environment, databases follow a strict naming convention. The **tenant
+string** has a single leading capital, rest lower-case (e.g. `Towfoundation`):
+
+| Family | Pattern | Contents |
+|---|---|---|
+| Platform | `Core`, `Forecast`, `Team` | Shared infrastructure (not tenant-scoped). |
+| Tenant (active) | `Client_<Tenant>` | Live working data for one client — e.g. `Client_Towfoundation`. |
+| Archive | `Archive_<Tenant>` | Old archived rows; **same table schema** as the matching `Client_` DB. |
+| Tenant logs | `Logs_<Tenant>` | Per-client activity/audit logs. |
+| Framework logs | `Logs` | Generic 2.0 logs not tied to any client. |
+
+**Resolving a tenant string from a client name:** query `Core.Clients`. The
+`clientIdentifier` field **is** the exact suffix used in `Client_`, `Archive_`, and
+`Logs_` database names; the `name` field is the human-readable label. Look up by either
+to find the other:
+
+```sql
+SELECT
+    name,
+    clientIdentifier
+FROM Clients
+WHERE
+    name LIKE '%<keyword>%'
+```
+
+A client whose `clientIdentifier` is `Towfoundation` therefore lives in
+`Client_Towfoundation`, `Archive_Towfoundation`, and `Logs_Towfoundation`.
+
+#### Non-production environments
+
+All non-production environments are **all-in-one**: a single cluster per environment
+holds `Core`, `Client_<Tenant>`, `Archive_<Tenant>`, and `Logs_<Tenant>` together
+(no family split). Region/reader routing still applies per cluster.
+
+| Environment (aliases) | Host |
+|---|---|
+| `dev-sandbox` / `sandbox-dev` / developer sandbox | `dev.sandbox.database.togahub.com` |
+| `client-sandbox` / `sandbox-client` | `client.sandbox.database.togahub.com` |
+| `client-alpha` / `alpha-client` | `alpha.client.database.togahub.com` |
+| `client-beta` / `beta-client` | `beta.client.database.togahub.com` |
+| `client-gamma` / `gamma-client` | `gamma.client.database.togahub.com` |
+| `qa-task` | `task.qa.database.togahub.com` |
+| `qa-hotfix` | `hotfix.qa.database.togahub.com` |
+| `qa-alpha` | `alpha.qa.database.togahub.com` |
+| `qa-beta` | `beta.qa.database.togahub.com` |
+| `qa-gamma` | `gamma.qa.database.togahub.com` |
+| `qc-task` | `task.qc.database.togahub.com` |
+| `qc-hotfix` | `hotfix.qc.database.togahub.com` |
+| `qc-security` | `security.qc.database.togahub.com` |
+| `qc-performance` | `performance.qc.database.togahub.com` |
+| `qc-alpha` | `alpha.qc.database.togahub.com` |
+| `qc-beta` | `beta.qc.database.togahub.com` |
+| `qc-gamma` | `gamma.qc.database.togahub.com` |
+| `stage` / `staging` | `stage.database.togahub.com` |
+| `demo` | `demo.database.togahub.com` |
+
+> **Credentials** are managed via the database/MCP environment config — **never stored
+> in this repo or in any committed file** (per `rules/common/security.md` and
+> `git-workflow.md`). Do not paste DB usernames or passwords into knowledge docs, code,
+> or commits.
+
 ## Model layer
 
 Each DB table has a model. Every model must define:

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

@@ -3,5 +3,3 @@
 | Doc | Summary | Files |
 |-----|---------|-------|
 | [API (api2 / TOGa API v2) Architecture](architecture.md) | `api2` is the backend powering the public **TOGa 2.0 API**. | api2/Controller/Index.php, api2/Component/Api/V2/V2.php, api2/Component/Api/Cxml/Cxml.php, api2/Component/Api/V2/Response/Response.php, api2/Config/ |
-| [Error Response Envelope](features/error-response.md) | Every api2 action method returns the same three-key envelope. | api2/Controller/Index.php |
-| [Health Check Endpoint](features/health-endpoint.md) | `GET /health` returns HTTP 200 with an empty JSON object (`{}`). | api2/Controller/Index.php |

package/knowledge/INDEX.md

@@ -11,7 +11,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 
 - **_underscore** (_Underscore) _(framework core)_ — 2 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
 - **worker2** (Worker) — 3 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
-- **api2** (API) — 3 doc(s) → [2.0/apps/api2/INDEX.md](2.0/apps/api2/INDEX.md)
+- **api2** (API) — 1 doc(s) → [2.0/apps/api2/INDEX.md](2.0/apps/api2/INDEX.md)
 
 ## Clients
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toga-ai",
-  "version": "1.0.23",
+  "version": "1.0.25",
   "description": "TOGA Technology Team Claude Knowledge System — shared AI coding harness with skills, knowledge base CLI, and project installer for Claude Code.",
   "keywords": [
     "claude",
@@ -15,7 +15,7 @@
   "homepage": "https://togatech.com",
   "repository": {
     "type": "git",
-    "url": "https://github.com/TOGATechnology/claude"
+    "url": "https://github.com/agilantsolutions/claude"
   },
   "license": "UNLICENSED",
   "private": false,

package/scripts/install.js

@@ -510,16 +510,15 @@ function main() {
 
   const bundleVersion = getBundleVersion();
 
-  // Auto-upgrade if npx served a stale cached version (common on Windows).
-  // Skip during --post-install — npm already ensured the right version.
+  // Warn if npx served a stale cached version (common on Windows). Never block — install
+  // the current bundle now and let the user update afterwards.
   if (!isPostInstall) {
     const latestVersion = getLatestNpmVersion();
     if (latestVersion && semverLt(bundleVersion, latestVersion)) {
       console.log('');
-      console.log('  Stale version detected (toga-ai@' + bundleVersion + ' → toga-ai@' + latestVersion + '). Auto-upgrading...');
-      const upgradeArgs = ['toga-ai@' + latestVersion, '--yes'].concat(args);
-      const upgrade = spawnSync('npx', upgradeArgs, { stdio: 'inherit', shell: process.platform === 'win32' });
-      process.exit(upgrade.status ?? 0);
+      console.log('  ⚠ Running toga-ai@' + bundleVersion + ' — toga-ai@' + latestVersion + ' is available.');
+      console.log('  Update with: npm cache clean --force && npx toga-ai@latest');
+      console.log('  (Continuing install with current bundle...)');
     }
   }
 
@@ -673,12 +672,28 @@ function main() {
 
   // Knowledge — git repo if available (has team-captured docs), else npm bundle
   // .claude/knowledge/ is a mirror — update when content changes so teammates get captured docs
-  const knowledgeSrc = path.join(knowledgeDir, 'knowledge');
   const knowledgeDest = path.join(claudeDir, 'knowledge');
   let knowledgeStats = { added: 0, updated: 0, unchanged: 0 };
-  if (fs.existsSync(knowledgeSrc)) {
-    try { knowledgeStats = copyDir(knowledgeSrc, knowledgeDest, { updateIfChanged: true }); }
-    catch (e) { errors.push('knowledge: ' + e.message); }
+
+  // Always install npm bundle knowledge first — this guarantees every file published
+  // in this version is present, regardless of what the git repo contains.
+  const bundleKnowledgeSrc = path.join(PACKAGE_ROOT, 'knowledge');
+  if (fs.existsSync(bundleKnowledgeSrc)) {
+    try { knowledgeStats = copyDir(bundleKnowledgeSrc, knowledgeDest, { updateIfChanged: true }); }
+    catch (e) { errors.push('knowledge (bundle): ' + e.message); }
+  }
+
+  // Then overlay git repo on top — picks up any docs newer than this npm bundle.
+  // Git is additive only: it never removes files the bundle already installed.
+  if (knowledgeDir !== PACKAGE_ROOT) {
+    const gitKnowledgeSrc = path.join(knowledgeDir, 'knowledge');
+    if (fs.existsSync(gitKnowledgeSrc)) {
+      try {
+        const gitStats = copyDir(gitKnowledgeSrc, knowledgeDest, { updateIfChanged: true });
+        knowledgeStats.added += gitStats.added;
+        knowledgeStats.updated += gitStats.updated;
+      } catch (e) { /* non-fatal — bundle layer already installed */ }
+    }
   }
   console.log('  ✓ Knowledge (' + countMd(knowledgeDest) + ' docs): ' + fmtStats(knowledgeStats));