toga-ai 1.0.15 → 1.0.17

package/knowledge/2.0/apps/api2/features/error-response.md

@@ -0,0 +1,49 @@
+---
+title: Error Response Envelope
+framework: "2.0"
+repo: api2
+project: TOGa API
+client: shared
+type: feature
+status: active
+updated: 2026-06-09
+owners: []
+files:
+  - api2/Controller/Index.php
+related:
+  - 2.0/apps/api2/architecture.md
+  - 2.0/apps/api2/features/health-endpoint.md
+---
+
+## Summary
+Every api2 action method returns the same three-key envelope. Clients depend on
+this contract — deviating from it breaks consumers silently.
+
+## Envelope structure
+```php
+return [
+    'success' => true,    // bool
+    'data'    => $result, // mixed — null on error
+    'errors'  => [],      // string[] — empty on success
+];
+```
+
+## Error response
+```php
+return [
+    'success' => false,
+    'data'    => null,
+    'errors'  => ['Order not found'],
+];
+```
+
+## HTTP status codes
+The framework maps `success: false` responses to HTTP 4xx/5xx via the controller
+base class. Do not manually set status codes — return the envelope and let the
+framework decide.
+
+## Gotchas / known issues
+- Never return a raw string or a bare array — the JS client checks `response.success`
+  and crashes if the key is missing.
+- `errors` must always be an array, even for a single error. Never pass a string.
+- `data` must be present even on error — pass `null`, not omit the key.

package/knowledge/2.0/apps/api2/features/health-endpoint.md

@@ -0,0 +1,47 @@
+---
+title: Health Check Endpoint
+framework: "2.0"
+repo: api2
+project: API
+client: shared
+type: feature
+status: active
+updated: 2026-06-09
+owners: [jcardinal]
+files:
+  - api2/Controller/Index.php
+related:
+  - 2.0/apps/api2/architecture.md
+---
+
+## Summary
+
+`GET /health` returns HTTP 200 with an empty JSON object (`{}`). It exists solely for
+Elastic Beanstalk and load-balancer health probes — not for application-level health
+checks.
+
+## How it works
+
+The route is handled in `Controller/Index.php` `api()` before any authentication, DB
+registration, or Sentry initialization runs. This keeps it as fast and dependency-free
+as possible so EB/ALB probes never time out due to a slow DB or misconfigured secret.
+
+```
+GET /health
+  → Controller/Index.php::api()
+      → early-exit: echo '{}', HTTP 200
+```
+
+## Gotchas / known issues
+
+- **Never add auth or DB calls to this route.** The probe fires every few seconds from
+  every AZ. Adding overhead here will cause false-positive unhealthy marks and
+  unnecessary instance replacements.
+- **Do not change the response body.** Some ALB rules pattern-match on `{}`. A non-empty
+  body or a different content type may cause the probe to fail even on HTTP 200.
+- If the endpoint starts returning non-200, EB will terminate and replace the instance —
+  you will lose in-flight requests with no warning in application logs.
+
+## Related docs
+
+- [api2 Architecture](../architecture.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toga-ai",
-  "version": "1.0.15",
+  "version": "1.0.17",
   "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/scripts/install.js

@@ -657,6 +657,9 @@ function main() {
   const action = updateClaudeMd(projectRoot, skillNames, harnessDir, 'npm bundle v' + bundleVersion);
   console.log('  ✓ CLAUDE.md ' + action);
 
+  // Write version marker so /kickoff can detect stale installs
+  try { fs.writeFileSync(path.join(claudeDir, 'toga-ai.version'), bundleVersion, 'utf8'); } catch (e) {}
+
   // ECC global integration — detect and report
   const eccPath = detectEcc();
   if (eccPath) {

package/skills/kickoff/SKILL.md

@@ -5,6 +5,35 @@ description: Start-of-session context loader for TOGA Technology projects. Run t
 
 # Kickoff — prime a coding session from the team knowledge base
 
+## Step 0 — Auto-update check (runs before anything else)
+
+Before loading any context, check whether the installed harness is up to date:
+
+```bash
+INSTALLED=$(cat .claude/toga-ai.version 2>/dev/null || echo "unknown")
+LATEST=$(node -e "const {execSync}=require('child_process');try{process.stdout.write(execSync('npm view toga-ai version',{timeout:5000}).toString().trim())}catch{process.stdout.write('unknown')}" 2>/dev/null)
+```
+
+**If `INSTALLED` is `unknown`** — version file missing (project not yet installed). Skip and continue to Step 1.
+
+**If `LATEST` is `unknown`** — npm unreachable (offline/timeout). Skip silently and continue to Step 1.
+
+**If `INSTALLED` equals `LATEST`** — already up to date. Continue to Step 1.
+
+**If `INSTALLED` differs from `LATEST`** — auto-upgrade now, then continue:
+
+```bash
+npx toga-ai@latest
+```
+
+Tell the developer:
+> "Updated toga-ai from v`INSTALLED` → v`LATEST`. Skills, agents, and rules refreshed."
+
+If the upgrade fails, warn and continue — a stale install beats a blocked session:
+> "⚠ Auto-update to v`LATEST` failed. Run `npx toga-ai@latest` manually when convenient."
+
+
+
 Load the right knowledge before the developer starts coding. **Never assume missing
 facts — ask.** Heuristics may pre-fill a *suggested default* in a question, but record
 nothing without confirmation.