toga-ai 1.0.147 → 1.0.148

package/knowledge/CONVENTIONS.md

@@ -8,10 +8,13 @@
 
 ## The two axes
 
-1. **Framework first.** Everything app- or framework-related lives under `1.0/` or
-   `2.0/`. These are the two PHP frameworks:
-   - **1.0** — the `App_` framework; core repo **`library`**.
-   - **2.0** — the `_underscore` framework; core repo **`_underscore`**.
+1. **Framework first.** Everything app- or framework-related lives under `1.0/`,
+   `2.0/`, or `standalone/`:
+   - **1.0** — the `App_` PHP framework; core repo **`library`**.
+   - **2.0** — the `_underscore` PHP framework; core repo **`_underscore`**.
+   - **standalone** — apps that belong to **no** PHP framework (e.g. `togatech`, a React/TS
+     site; `forward`). They live under `standalone/apps/<repo>/`, have **no framework core**,
+     and depend on nothing implicitly. Not everything is 1.0 or 2.0.
 2. **Shared vs. client.** Within a framework, app/feature/architecture knowledge
    lives under `apps/<repo>/`. Anything specific to a single client lives at the top
    level under `clients/<client>/` and tags its `framework` in frontmatter.
@@ -29,6 +32,8 @@ knowledge/
 ├── 2.0/
 │   ├── apps/<repo>/architecture.md + features/*.md + workflows/*.md
 │   └── standards/*.md     # 2.0 coding standards (_underscore)
+├── standalone/
+│   └── apps/<repo>/architecture.md + features/*.md  # non-PHP apps (e.g. togatech); no core
 └── clients/<client>/
     ├── profile.md
     ├── features/*.md      # client-specific feature overrides (link back to apps/)
@@ -49,13 +54,14 @@ The shared identity/topology of every repo. Maintained **only by the skills**.
 
 - `repo` — on-disk repo/folder name (the key; unique).
 - `project` — logical project name.
-- `framework` — `"1.0"` or `"2.0"`.
+- `framework` — `"1.0"`, `"2.0"`, or `"standalone"` (non-PHP apps with no framework core).
 - `role` — `"core"` (the framework base every same-framework repo depends on) or `"app"`.
 - `dependsOn` — additional repos this one depends on beyond the framework core
   (e.g. `api2` may later depend on `apiproxy`).
 
 **Dependency loading:** every repo implicitly depends on its framework's `core` repo
-(`_underscore` for 2.0, `library` for 1.0), plus any transitive `dependsOn`.
+(`_underscore` for 2.0, `library` for 1.0), plus any transitive `dependsOn`. `standalone`
+apps have no framework core, so they load only themselves plus any explicit `dependsOn`.
 `node knowledge.js deps --repo=<repo>` resolves the full load order.
 
 ## Client app-scope (`apps:` on `profile.md`)

package/knowledge/standalone/apps/togatech/features/seo-aeo-geo-prerender.md

@@ -6,8 +6,8 @@ project: TOGA Technology Website
 client: shared
 type: feature
 status: active
-updated: 2026-06-18
-owners: ["ajean"]
+updated: 2026-06-19
+owners: ["ajean", "jcardinal"]
 files:
   - togatech/vite.config.ts
   - togatech/scripts/prerender.mjs
@@ -24,7 +24,7 @@ related: []
 ---
 
 ## Summary
-Makes togatech.com visible and citable to search engines **and** AI answer engines (ChatGPT/Perplexity/Claude search, Google AI Overviews). The site is a CSR-only Vite/React SPA, so non-JS crawlers saw an empty `<div id="root">`. This feature fixes a production de-indexing bug and adds **build-time prerendering** so every static route ships real HTML, plus single-source per-page meta and JSON-LD structured data. Shipped on branches `fix-seo-deindex-emergency` (PR #29) and `feature-seo-aeo-prerender` (PR #30) — **not yet merged/deployed** as of 2026-06-18.
+Makes togatech.com visible and citable to search engines **and** AI answer engines (ChatGPT/Perplexity/Claude search, Google AI Overviews). The site is a CSR-only Vite/React SPA, so non-JS crawlers saw an empty `<div id="root">`. This feature fixes a production de-indexing bug and adds **build-time prerendering** so every static route ships real HTML, plus single-source per-page meta and JSON-LD structured data. Shipped on branches `fix-seo-deindex-emergency` (PR #29) and `feature-seo-aeo-prerender` (PR #30); **merged into `_production` on 2026-06-19** (Contact page conflict resolved — see gotchas).
 
 ## Key files / entry points
 - `vite.config.ts` — `robotsPlugin()` now gates on **Vite `mode`** (was `NODE_ENV && VITE_ENV`).
@@ -35,7 +35,7 @@ Makes togatech.com visible and citable to search engines **and** AI answer engin
 
 ## How it works
 1. **robots:** `robotsPlugin` copies `robots.prod.txt` only when `mode === "production"`; beta/gamma/dev get `robots.dev.txt` (`Disallow: /`). `robots.prod.txt` carries an explicit AI-bot allow-list (GPTBot, ClaudeBot, PerplexityBot, …) + `https://` sitemap.
-2. **prerender:** `npm run build` = `tsc && vite build && node scripts/prerender.mjs`. The script serves `dist/` (reading the original shell once, serving it for all nav routes), snapshots each route in headless Chrome, and writes `dist/<route>/index.html`. Runs in a real browser, so **no SSR/window guards needed**.
+2. **prerender:** `npm run build` = `tsc && vite build && npx puppeteer browsers install chrome && node scripts/prerender.mjs` (the Chrome-install step was added 2026-06-19 — see gotchas). The script serves `dist/` (reading the original shell once, serving it for all nav routes), snapshots each route in headless Chrome, and writes `dist/<route>/index.html`. Runs in a real browser, so **no SSR/window guards needed**.
 3. **meta:** each page renders `<Seo {...FIELDS.meta} />` — title/description/keywords/canonical/OG/Twitter from one place per page; canonical/OG URLs derived from one `SITE_URL`. `<JsonLd>` (Helmet `<script type="application/ld+json">`) is baked into the snapshot.
 4. **structured data:** Organization + WebSite site-wide (AppLayout), per-page BreadcrumbList (Seo), platform SoftwareApplication (OurPlatform), LocalBusiness×5 (from Contact locations), Person (from About team) — all **derived from existing FIELDS** (single source).
 
@@ -48,7 +48,10 @@ None — uniform.
 ## Gotchas / known issues
 - **De-indexing bug (root cause):** `robotsPlugin` required `NODE_ENV && VITE_ENV==="production"`, but build scripts set neither → every build shipped `robots.dev.txt` (`Disallow: /`). **Do NOT gate robots on `NODE_ENV`** — `vite build` sets it to `production` for *every* mode, which would expose beta/gamma. Gate on Vite `mode`.
 - **`.npmrc` has `ignore-scripts=true`** → the `postbuild` lifecycle hook never fires. Prerender is therefore chained directly in the `build` script, not a `postbuild` hook.
-- **Prerender tooling:** `vite-react-ssg` supports React Router **6 only** (project is RR 7.9); `react-snap` is stale (2022) and won't launch on Node 24. Hence a custom Puppeteer snapshot. Puppeteer's Chrome must be installed at build time: `npx puppeteer browsers install chrome`.
+- **Prerender tooling:** `vite-react-ssg` supports React Router **6 only** (project is RR 7.9); `react-snap` is stale (2022) and won't launch on Node 24. Hence a custom Puppeteer snapshot.
+- **🔴 Chrome must be installed in the build (now wired in):** Amplify/CodeBuild's `npm ci` does **not** download a browser, so `puppeteer.launch()` fails with `Could not find Chrome (ver. …)` at `/root/.cache/puppeteer`. Fixed 2026-06-19 by adding `npx puppeteer browsers install chrome` to the `build` script immediately before `node scripts/prerender.mjs` (same default cache `launch()` resolves from). puppeteer 25 also requires **Node ≥ 22.12** — set the Amplify image accordingly. (The step re-downloads ~150 MB per build unless `/root/.cache/puppeteer` is cached.)
+- **🔴 `package-lock.json` must be committed:** Amplify preBuild runs `npm ci`, which refuses to run without a committed lockfile (`npm error code EUSAGE`) and will **not** generate one. The lockfile is not gitignored — it was simply never committed; `npm install` once and commit it.
+- **Contact page merge (2026-06-19):** when merging the SEO/AEO feature into `_production`, `ContactPage.tsx` conflicted. Resolution: keep production's reCAPTCHA conditional wrap (`GoogleReCaptchaProvider` mounts only when `VITE_RECAPTCHA_V3_SITE_KEY` is set) **and** the `<Seo>`/`<JsonLd>` components; drop the incoming `<Helmet>` block (superseded by `<Seo>`).
 - **Prerender fail-fast:** a route that never mounts (`#root > *` times out) aborts the build with `process.exit(1)` — otherwise it would snapshot the empty shell (no SEO/JSON-LD) and still exit 0.
 - **🔴 Hosting requirement:** CloudFront/S3 must serve each prerendered `dist/<route>/index.html` for its path; a blanket SPA rewrite to root `index.html` serves the empty shell and defeats the prerender.
 - **og:image dedupe:** static OG/Twitter tags were removed from `index.html` because `<Seo>` emits per-page ones (Helmet appends rather than replacing pre-existing static tags → duplicates otherwise).
@@ -56,6 +59,7 @@ None — uniform.
 - **Build size:** JS bundle is ~14.8 MB (4.9 MB gzip) — a real CWV/LCP risk; code-splitting is a separate follow-up.
 
 ## Change history
+- 2026-06-19 — Merged SEO/AEO into `_production` (resolved ContactPage conflict: reCAPTCHA + Seo/JsonLd, dropped Helmet). Fixed Amplify build: committed `package-lock.json` (npm ci EUSAGE) and added `npx puppeteer browsers install chrome` to the build before prerender. (jcardinal)
 - 2026-06-18 — Initial SEO/AEO/GEO implementation: robots mode-gate + AI allow-list + sitemap/llms; Puppeteer prerender (fail-fast); shared `<Seo>` single-source meta + canonical; JSON-LD (Organization/WebSite/Breadcrumb/SoftwareApplication/LocalBusiness×5/Person×12). PRs #29 + #30, pending merge. (ajean)
 
 ## Related docs

package/package.json

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