toga-ai 1.0.433 → 1.0.434

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

@@ -3,6 +3,7 @@
 | Doc | Summary | Files |
 |-----|---------|-------|
 | [Tools (1.0 Internal-Tools App) Architecture](architecture.md) | **Tools** is a standalone 1.0 (`App_`) application that houses many small internal tools behind simple interfaces, gated by Client_True staff persona. | tools/index.php, tools/_/app/framework.php, tools/_/app/frameworkindex.php, tools/assets/img/favicon/favicon.ico, tools/assets/img/favicon/favicon-32x32.png, tools/assets/img/favicon/favicon-16x16.png, tools/assets/img/favicon/apple-touch-icon.png, tools/_/app/auth.php, tools/_/app/nav.php, tools/common/header.php, tools/common/footer.php, tools/mvc/get.php, tools/mvc/_TEMPLATE/get.php, tools/docs/ADDING_A_TOOL.md |
+| [Design Demo Admin](features/design-demo-admin.md) | A self-serve admin UI at **`/design`** in the SSO-protected **Tools** app that lets the design team publish self-contained "Claude Design" HTML exports as **ver | tools/_/app/design/github.php, tools/mvc/design/get.php, tools/mvc/design/post.php, tools/assets/css/design.css, tools/assets/js/design.js, tools/_/app/frameworkindex.php, tools/_/app/nav.php, tools/composer.json |
 | [Tools — Developers Folder (UUID & Password Generators)](features/developer-tools.md) | The first two tools shipped in the Tools app, both under the **Developers** folder and gated to personas **Development Team** / **TOGa Technology**. | tools/mvc/developers/uuid/get.php, tools/mvc/developers/password/get.php |
 | [Tools MVC — Routing, CSRF & App_Database Access Patterns](features/mvc-data-access-patterns.md) | The load-bearing 1.0 (`App_`) framework conventions a developer needs when adding a page to the Tools app — URL routing, CSRF, and DB access through `App_Databa | tools/_/app/nav.php, tools/mvc/get.php |
 | [Tools Persona-Gated Navigation (App_Nav)](features/persona-gated-navigation.md) | `App_Nav` is the Tools app's two-level, **persona-gated** navigation. | tools/_/app/nav.php, tools/mvc/get.php |

package/knowledge/1.0/apps/tools/architecture.md

@@ -91,6 +91,16 @@ Create `mvc/<folder>/<tool>/get.php` (copy `mvc/_TEMPLATE/get.php`), add one ent
   **accepted this for now** (developer decision, 2026-06-25). Future remediation: git-ignore the
   config files and rotate all exposed credentials. (Location only — no values recorded here.)
 - **SSO initiation + replay defense are open items** — see `features/saml-sso-auth.md`.
+- **Framework-level Sentry error reporting is an open gap.** Prod printed "Sentry is not
+  installed" because `sentry/sentry` was missing from `composer.json` (added `^4.10`; sibling
+  apps use `^4.10`/`^4.19`). But even with Sentry in `vendor/`, the 1.0 framework does **not**
+  auto-require `vendor/autoload.php` (the `App_Talos_S3` pattern `require_once`s it explicitly),
+  so framework-level Sentry reporting for Tools still does not load. Any code path that needs a
+  composer package must `require_once` the autoloader itself.
 
 ## Change history
+- 2026-07-24 — Added the SSO-gated **Design Demo Admin** tool at `/design` (`App_Design_Github`
+  + `mvc/design/*` + namespaced assets + a `design` nav group), which publishes versioned demos
+  into the `forward` repo over the GitHub API (see `features/design-demo-admin.md`). Noted the
+  framework-level Sentry gap (composer autoloader not auto-required) in Known issues (jcardinal)
 - 2026-06-26 — Documented app-local favicons under `assets/img/favicon/` (registered in `_/app/frameworkindex.php`, not the shared `resources/` set) + the per-app-asset convention; refreshed the home-route description for one-step SSO sign-in and the persona-less empty-state (jcardinal)

package/knowledge/1.0/apps/tools/features/design-demo-admin.md

@@ -0,0 +1,171 @@
+---
+title: Design Demo Admin
+framework: "1.0"
+repo: tools
+project: Tools
+client: shared
+type: feature
+status: active
+updated: 2026-07-24
+owners: [jcardinal]
+files:
+  - tools/_/app/design/github.php
+  - tools/mvc/design/get.php
+  - tools/mvc/design/post.php
+  - tools/assets/css/design.css
+  - tools/assets/js/design.js
+  - tools/_/app/frameworkindex.php
+  - tools/_/app/nav.php
+  - tools/composer.json
+related:
+  - ../architecture.md
+  - ../features/persona-gated-navigation.md
+  - ../features/saml-sso-auth.md
+  - ../workflows/deploy-to-elastic-beanstalk-al2023.md
+  - ../../../standalone/apps/forward/features/static-demo-hosting.md
+---
+
+## Summary
+
+A self-serve admin UI at **`/design`** in the SSO-protected **Tools** app that lets the
+design team publish self-contained "Claude Design" HTML exports as **versioned demos** — no
+developer, no git, no local checkout. It writes into the **`agilantsolutions/forward`** repo
+(branch `_main`) over the **GitHub REST API**, and the demos stay **publicly hosted by
+`forward`** at `demo.togatech.com` (URLs unchanged). See
+[Static Demo Hosting](../../../standalone/apps/forward/features/static-demo-hosting.md).
+
+The tool **moved out of `forward` into `tools` this session.** Rationale: `forward` has no
+auth (it is only a forwarder/hoster); `tools` is SSO-protected and is the home for internal
+tools. The admin UI is now behind SSO, but the data (demos + manifests) still lives in and is
+served from the `forward` repo.
+
+## Key files / entry points
+
+- `_/app/design/github.php` — class **`App_Design_Github`**: all GitHub REST + domain logic
+  ported from the old single-file tool (`ghApi` / `ghListDir` / `ghReadFile` /
+  `ghCommitFiles` / `ghDeletePaths`, project/version/tab CRUD, upload validation, redirect-
+  stub builder).
+- `mvc/design/get.php` — route `/design` (page shell). Self-guards with
+  `App_Auth::requireAuth([...])` + `App_Page::validateCrossSiteRequestForgery()`.
+- `mvc/design/post.php` — AJAX action dispatcher.
+- `assets/css/design.css`, `assets/js/design.js` — namespaced under `.design-tool`,
+  registered globally in `_/app/frameworkindex.php`.
+- `_/app/nav.php` — a `design` group, action **`Design Demos`** → `/design`, personas
+  `['TOGa Technology','Development Team']`.
+
+## How it works
+
+### GitHub API access (no filesystem)
+
+The tool runs on the SSO-protected Tools EB host, not a git checkout, so **all** repo access
+is over the GitHub API:
+
+- **Reads / listing:** GitHub **Contents API** (`ghReadFile` uses the raw media type
+  `Accept: application/vnd.github.raw` so multi-MB exports stream up to 100 MB — the base64
+  Contents response inlines only ≤1 MB and silently returns empty content above that).
+- **Writes:** GitHub **Git Data API** — blob → tree → commit → update-ref — so a publish is
+  an **atomic multi-file commit** (version files + regenerated stub + `project.json` land in
+  one commit).
+- Publishing pushes to `forward`'s `_main`, which triggers `forward`'s EB auto-deploy — demos
+  go live in a few minutes; there is no staging step.
+
+### Data model (lives in the `forward` repo)
+
+- Per project: **`<project>/project.json`** — `{ title, latest, hidden, tabs[], versions[] }`.
+  Human detail (label/author/notes/date) lives in the manifest, not the URL. A directory is a
+  managed demo **iff it contains `project.json`**.
+- Per version: **`<project>/vN/index.html`** — sequential `/v1`, `/v2`, `/v3` URL folders
+  (not semver, not date-based).
+- Repo root **`tabs.json`** — `{ "tabs": [...] }`, the ordered tab list.
+- The bare `/<project>` serves an auto-generated `index.html` **stub** that
+  meta-refresh/JS-redirects (relative `./vN/`) to the newest **visible** version; regenerated
+  on every publish/unlist.
+
+### Multi-tab membership
+
+The project.json `tab` **scalar** became a **`tabs` array**. It is read **backward-
+compatibly** (an old `tab` scalar is honored) and **lazily migrated** — the scalar is dropped
+on the next write of that project.json. Tab management via a per-pill "⋯" menu:
+
+- **Rename / delete** — rewrite `tabs.json` **and** every affected `project.json` in one
+  **atomic** commit.
+- **Reorder** — a single-file `tabs.json` commit, validated as a **permutation** of the
+  existing list.
+
+### Actions & UX
+
+- **Publish a version** — uploads a self-contained HTML export as the next `vN/index.html`,
+  appends a version entry, regenerates the stub, commits.
+- **Remove version** — collapses the version out of the main list; unlisted versions sit
+  behind a per-project "Show N unlisted" collapsible.
+- **Unlist a project ("Remove")** — reversible `hidden` flag; files are not deleted.
+- **Hard-delete a whole project** — `ghDeletePaths()` reads the head tree recursively,
+  rebuilds a fresh tree **excluding the project folder** (exact folder-boundary prefix match),
+  commits, then PATCHes the ref. Offered alongside the reversible unlist.
+- **Set latest / toggle version / edit version / toggle project / set project tabs** — commit
+  the relevant `project.json` (metadata-only edits do not rebuild the stub).
+- **Copy URL** and **Copy Claude Design prompt** — clipboard helpers.
+- **Single scroll region** — `#projects` is the only scroll area; header/tabbar are fixed, so
+  switching tabs never shifts layout.
+- The Claude Design export **prompt modal** forces a dark `<pre>` background + light text with
+  `!important` (the global light `pre` theme otherwise wins).
+
+### Hardening
+
+- `isValidProjectName()` guards on `setLatest` / `toggleVersion` / `editVersion` /
+  `toggleProject` / `setProjectTabs`.
+- `upload()` **errors on corrupt project.json** instead of silently resetting history.
+- Inline `window.DESIGN_CONFIG` uses `JSON_HEX_*` flags.
+- Input length caps, version-id regex guard, HTML content sniff on upload; no client-facing
+  leakage of GitHub/curl error detail.
+
+## Access control
+
+Behind Tools SSO. The page self-guards with `App_Auth::requireAuth([...])` and
+`App_Page::validateCrossSiteRequestForgery()`; the nav action is gated to the
+`TOGa Technology` and `Development Team` personas. This is the key improvement over the old
+`forward` tool, which had **no** authentication.
+
+## GitHub token
+
+`App_Design_Github::token()` reads the token from `getenv()` **AND** `$_SERVER` **AND**
+`$_ENV`, then falls back to a `[design] github_token` config key for local dev. The EB
+environment property is named **`GITHUB_TOKEN`** (value not recorded here). It is never
+logged or echoed. Reading all three superglobals is required because php-fpm on AL2023
+defaults to `clear_env=yes` — see the deploy workflow gotcha. Prefer a **fine-grained PAT**
+scoped to the `forward` repo's Contents R/W.
+
+## Client variations
+
+None — internal/shared design-team tool.
+
+## Gotchas / known issues
+
+- **`curl_close()` is deprecated as of PHP 8.5** (and a no-op since 8.0). The 1.0 framework
+  on PHP 8.5 promotes deprecations to `ErrorException`, which aborts the request — every
+  GitHub call threw and the tool returned "Unexpected error" (0 projects). Fix: removed all
+  `curl_close()` calls. Audit ported code for other deprecated-in-8.x calls.
+- **Contents API inlines only ≤1 MB** — read exports with the raw media type (see above).
+- **Publishing pushes to `forward`'s `_main`** and triggers EB auto-deploy; no staging.
+- Never hardcode the token in tracked source — a leaked `ghp_`/PAT must be rotated.
+
+## Change history
+
+- 2026-07-24 — Moved the Design Demo Admin from `forward` into the SSO-protected `tools` app
+  (`App_Design_Github` + `/design` MVC route + namespaced assets + nav entry); still commits
+  to `agilantsolutions/forward` `_main` and demos stay hosted at `demo.togatech.com`. Added
+  multi-tab membership (`tabs` array, backward-compatible + lazy migration), tab
+  rename/delete/reorder via ⋯ menu (atomic multi-file commits; reorder validated as a
+  permutation), hard project delete (`ghDeletePaths` tree rebuild), unlisted-version collapse,
+  and a permanent single scroll region. Hardened project-name guards, corrupt-manifest
+  handling, and `JSON_HEX_*` inline config. Token now read from `getenv()`/`$_SERVER`/`$_ENV`
+  (`GITHUB_TOKEN` EB property) for the AL2023 php-fpm `clear_env` case; removed `curl_close()`
+  for PHP 8.5. (jcardinal)
+
+## Related docs
+
+- [Tools Architecture](../architecture.md)
+- [Static Demo Hosting](../../../standalone/apps/forward/features/static-demo-hosting.md)
+- [Deploying Tools to Elastic Beanstalk (AL2023)](../workflows/deploy-to-elastic-beanstalk-al2023.md)
+</content>
+</invoke>

package/knowledge/1.0/apps/tools/workflows/deploy-to-elastic-beanstalk-al2023.md

@@ -55,7 +55,9 @@ The old approach ran `ebs/setup_phpini.php` (now superseded) which called
 failed silently (it was wrapped in `ignoreErrors: true`), so `include_path` never picked up
 `/var/www/library`, producing fatal `require_once('_.php')` errors at runtime.
 
-The `application.ini` sets `include_path = ".:/var/www/library"`, upload/post limits (16M),
+The `application.ini` sets `include_path = ".:/var/www/library"`, upload/post limits
+(`upload_max_filesize=25M` / `post_max_size=30M`, raised from 16M so multi-MB design-demo HTML
+exports up to ~25MB post through — see `features/design-demo-admin.md`),
 `memory_limit = 2G`, `display_errors`, the `redis.so` extension, and the rediscluster session
 handler (`session.save_path` points at the ElastiCache cluster cfg endpoint). Session GC
 maxlifetime is 4 days.
@@ -100,6 +102,12 @@ setup — the git clone (`020`) deliberately does **not** use it (see gotchas).
 
 ## Gotchas (durable AL2023 / EB rules)
 
+- **php-fpm on AL2023 defaults to `clear_env=yes`, so `getenv()` cannot see EB environment
+  properties.** An EB environment property (e.g. `GITHUB_TOKEN`) that is set correctly still
+  returns `false` from `getenv()` under php-fpm on AL2023, because the FPM pool strips the
+  environment. Read such a value from **`getenv()` AND `$_SERVER` AND `$_ENV`** (the property
+  reaches PHP via the superglobals even when `getenv()` is blind), and fall back to a config
+  key for local dev. Never log/echo the value.
 - **Write new-deploy files to `/var/app/ondeck/<path>`, never `/var/www/html/<path>` during
   `container_commands`.** While container_commands run, `/var/www/html` still symlinks to the
   **old** app. After the deploy swap, `/var/app/ondeck` becomes `/var/app/current`
@@ -128,6 +136,9 @@ setup — the git clone (`020`) deliberately does **not** use it (see gotchas).
   returns `200` fast. Reusable for any TOGA app behind Elastic Beanstalk.
 
 ## Change history
+- 2026-07-24 — Added the php-fpm `clear_env=yes` gotcha (read EB env properties from
+  `getenv()`/`$_SERVER`/`$_ENV`) and raised `application.ini` upload/post limits to 25M/30M for
+  multi-MB design-demo exports (jcardinal)
 - 2026-06-26 — CONFIRMED + RESOLVED the SAML SSO return-leg gotcha: the `tools.togatech.com` EB environment had no HTTPS (443) listener at all; adding the HTTPS:443 listener + ACM cert covering the exact return hostname fixed the SSO return leg with no code change (jcardinal)
 - 2026-06-26 — Added the SAML SSO return-leg gotcha: a "connection timeout" on `https://<host>/sso` was a missing EB/ALB HTTPS (443) listener for the new `togatech.com` hostname (not PHP/SAML); documented the curl `http=000` vs `127.0.0.1` 200 diagnosis (jcardinal)
 - 2026-06-26 — Documented the AL2 → AL2023 (PHP 8.5) EB migration for Tools: package renames

package/knowledge/1.0/standards/framework-rules.md

@@ -112,6 +112,20 @@ are adding a column that only `worker` reads, the `.sql` file goes in `dbchanges
 Never create a `.sql` file inside a 1.0 application repo. The SQL that belongs in those
 repos is only query strings embedded in PHP code — not standalone migration files.
 
+## PHP 8.x deprecations abort the request (audit before running on 8.5)
+
+The 1.0 framework's error handler promotes PHP **deprecation notices to `ErrorException`**,
+which aborts the request. On PHP 8.5, a single deprecated call in a live code path is therefore
+a hard failure, not a silent notice — it surfaces to users as a generic error.
+
+- When porting or running 1.0 code on PHP 8.x, **audit for deprecated-in-8.x calls** in every
+  reachable code path before deploy.
+- Known offender: **`curl_close()`** — deprecated as of PHP 8.5 and a no-op since PHP 8.0.
+  Remove all `curl_close()` calls; the cURL handle is closed automatically. (This exact bug
+  made the Design Demo Admin tool throw on every GitHub call and render 0 projects.)
+- Do not suppress the deprecation with `@` (see the coding-style rules) — remove/replace the
+  deprecated call instead.
+
 ## Error handling in controllers
 
 Controllers must not let exceptions bubble up to the framework unhandled. Catch specific exceptions, log them, and return an appropriate response.

package/knowledge/INDEX.md

@@ -13,7 +13,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 - **walmarttechservices** (Walmart Tech Services) — 1 doc(s) → [1.0/apps/walmarttechservices/INDEX.md](1.0/apps/walmarttechservices/INDEX.md)
 - **test** (Test) — 13 doc(s) → [1.0/apps/test/INDEX.md](1.0/apps/test/INDEX.md)
 - **toga** (TOGa) — 2 doc(s) → [1.0/apps/toga/INDEX.md](1.0/apps/toga/INDEX.md)
-- **tools** (Tools) — 8 doc(s) → [1.0/apps/tools/INDEX.md](1.0/apps/tools/INDEX.md)
+- **tools** (Tools) — 9 doc(s) → [1.0/apps/tools/INDEX.md](1.0/apps/tools/INDEX.md)
 
 ## 2.0 framework
 
@@ -37,7 +37,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 
 - **togatech** (TOGA Technology Website) — 4 doc(s) → [standalone/apps/togatech/INDEX.md](standalone/apps/togatech/INDEX.md)
 - **websocket** (WebSocket Server) — 2 doc(s) → [standalone/apps/websocket/INDEX.md](standalone/apps/websocket/INDEX.md)
-- **forward** (Forwarder) — 4 doc(s) → [standalone/apps/forward/INDEX.md](standalone/apps/forward/INDEX.md)
+- **forward** (Forwarder) — 3 doc(s) → [standalone/apps/forward/INDEX.md](standalone/apps/forward/INDEX.md)
 
 ## Clients
 

package/knowledge/standalone/apps/forward/INDEX.md

@@ -2,7 +2,6 @@
 
 | Doc | Summary | Files |
 |-----|---------|-------|
-| [Forwarder Architecture](architecture.md) | Forwarder is a tiny **standalone PHP application** that powers TOGA's short, branded redirect domains. | forward/forward.ini, forward/index.php, forward/.htaccess, forward/.platform/httpd/conf.d/rewritemap.conf, forward/.ebextensions/rewritemap.config, forward/design/index.php, forward/composer.json |
-| [Design Demo Admin Tool](features/design-demo-admin.md) | A standalone, dependency-free PHP tool served at `https://demo.togatech.com/design` that lets the **design team** publish self-contained "Claude Design" HTML ex | forward/design/index.php, forward/tabs.json, forward/design/.config.example.php, forward/.gitignore, forward/.htaccess, forward/.ebextensions/php-uploads.config |
+| [Forwarder Architecture](architecture.md) | Forwarder is a tiny **standalone PHP application** that powers TOGA's short, branded redirect domains. | forward/forward.ini, forward/index.php, forward/.htaccess, forward/.platform/httpd/conf.d/rewritemap.conf, forward/.ebextensions/rewritemap.config, forward/composer.json |
 | [Encrypted-Link Handler](features/encrypted-link-handler.md) | A `index.php` feature in [Forwarder](../architecture.md) for redirect domains whose URL path carries an **encrypted token** that must be decoded before redirect | forward/index.php |
 | [Static Demo Hosting](features/static-demo-hosting.md) | A lightweight way to host self-contained static HTML pages (demos, exported designs, download landing pages) on the Forwarder app under a clean URL — e.g. | forward/.htaccess, forward/togadesk/index.html |

package/knowledge/standalone/apps/forward/architecture.md

@@ -14,7 +14,6 @@ files:
   - forward/.htaccess
   - forward/.platform/httpd/conf.d/rewritemap.conf
   - forward/.ebextensions/rewritemap.config
-  - forward/design/index.php
   - forward/composer.json
 related: []
 ---
@@ -76,7 +75,13 @@ The `.htaccess` at the repo root drives a plain-text lookup table:
   (e.g. `sos.*` → `/sos/`), it redirects to `/<subdomain>/` and serves that dir's
   `index.html`. Used for the bundled `sos/` Splashtop SOS download page.
 - **404** — otherwise returns a styled `404` echoing the unmatched `host + uri`.
-- **Design Demo Admin tool** — `/design` serves `design/index.php`, a self-serve UI for the design team to publish and version Claude Design HTML exports via the GitHub API. It runs as a normal directory request (not through the redirect map). See the [Design Demo Admin](features/design-demo-admin.md) feature doc.
+
+> **The Design Demo Admin tool moved out of `forward`.** As of 2026-07-24 the self-serve
+> publishing UI lives in the SSO-protected **Tools** 1.0 app at `/design` (see
+> `1.0/apps/tools/features/design-demo-admin.md`), and `forward/design/` was deleted. `forward`
+> still **stores** the demo data (per-project `project.json` + `vN/index.html`, repo-root
+> `tabs.json`) and **hosts** the demos publicly at `demo.togatech.com` (URLs unchanged); it no
+> longer contains the admin UI. Tools writes into this repo's `_main` over the GitHub API.
 
 ## Deployment (Elastic Beanstalk / Apache)
 
@@ -92,7 +97,7 @@ The `.htaccess` at the repo root drives a plain-text lookup table:
 - `composer.json` declares a `Togatech\Forward\` PSR-4 autoload over `src/` but has **no
   dependencies** and no `src/` is shipped today — the app is effectively a single
   `index.php` plus the Apache config.
-- **`DirectoryIndex index.html index.php`** in `.htaccess` makes `/design/` load `design/index.php` and lets nested static-demo version paths `/<project>/<vN>/` serve via Apache's normal directory index. The single-segment static-demo rewrite rule does not match two-segment paths, and the `index.php` map-miss fallback does not fire for real directories — so versioned demo URLs resolve as directory-index lookups.
+- **`DirectoryIndex index.html index.php`** in `.htaccess` lets nested static-demo version paths `/<project>/<vN>/` serve via Apache's normal directory index. The single-segment static-demo rewrite rule does not match two-segment paths, and the `index.php` map-miss fallback does not fire for real directories — so versioned demo URLs resolve as directory-index lookups.
 
 ## The `decrypt()` scheme
 
@@ -123,3 +128,4 @@ Treat this as obfuscation only. Anything genuinely sensitive must not rely on it
 - 2026-06-18 (jcardinal) — Initial architecture documentation; registered `forward`
   (Forwarder, standalone) in the knowledge base.
 - 2026-06-23 (jcardinal) — Added the `/design` Design Demo Admin route and a `DirectoryIndex index.html index.php` directive in `.htaccess` (enables `/design/` and nested `/<project>/<vN>/` demo paths).
+- 2026-07-24 (jcardinal) — Removed the Design Demo Admin tool from `forward` (deleted `forward/design/`); it now lives in the SSO-protected Tools 1.0 app (`1.0/apps/tools/features/design-demo-admin.md`). `forward` still stores and hosts the demo data/`tabs.json`; Tools writes to `_main` over the GitHub API.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toga-ai",
-  "version": "1.0.433",
+  "version": "1.0.434",
   "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/knowledge/standalone/apps/forward/features/design-demo-admin.md

@@ -1,202 +0,0 @@
----
-title: Design Demo Admin Tool
-framework: "standalone"
-repo: forward
-project: Forwarder
-client: shared
-type: feature
-status: active
-updated: 2026-06-25
-owners: ["jcardinal"]
-files:
-  - forward/design/index.php
-  - forward/tabs.json
-  - forward/design/.config.example.php
-  - forward/.gitignore
-  - forward/.htaccess
-  - forward/.ebextensions/php-uploads.config
-related:
-  - standalone/apps/forward/features/static-demo-hosting.md
-  - standalone/apps/forward/architecture.md
----
-
-## Summary
-
-A standalone, dependency-free PHP tool served at `https://demo.togatech.com/design` that
-lets the **design team** publish self-contained "Claude Design" HTML exports to the
-`forward` repo as **versioned demos** — no developer, no git, no local checkout required.
-It sits on top of [Static Demo Hosting](static-demo-hosting.md): static hosting serves the
-files; this tool is the self-serve UI that writes and versions them.
-
-The tool does **all** repo access over the **GitHub REST API** — never the local
-filesystem — because in production it runs on the Elastic Beanstalk host, not a git
-checkout. Publishing pushes a commit to `_main`, which triggers the existing EB
-auto-deploy ("live in a few minutes").
-
-## Key files / entry points
-
-- `forward/design/index.php` — the entire tool: a single-file PHP backend + HTML/JS UI.
-  `declare(strict_types=1)`. Served at `/design` (was `/admin`; renamed this session).
-- `forward/design/.config.example.php` — template for local dev config (the real
-  `.config.php` is git-ignored).
-- `forward/.gitignore` — ignores `design/.config.php` so a local token is never tracked.
-- `forward/.htaccess` — `DirectoryIndex index.html index.php` so `/design/` loads
-  `index.php`, and so nested `/<project>/<vN>/` paths serve via Apache's directory index.
-
-## How it works
-
-### GitHub API access (no filesystem)
-
-- **Reads / listing:** GitHub **Contents API**.
-- **Writes:** GitHub **Git Data API** — blob → tree → commit → update-ref — so a publish
-  is an **atomic multi-file commit** (the version's files + the regenerated stub +
-  `project.json` all land in one commit).
-- **Auth:** token from `getenv('FORWARD_GITHUB_TOKEN')` (an Elastic Beanstalk environment
-  property in prod) or an uncommitted `design/.config.php` for local dev. See gotchas — the
-  token must **never** live in the tracked `index.php`.
-
-### Versioning model (decided this session)
-
-- **Sequential `/v1`, `/v2`, `/v3` URL folders** — not semver, not date-based.
-- Each project has a **`project.json` manifest** at its folder root:
-  ```json
-  {
-    "title": "...", "latest": "v3", "hidden": false,
-    "versions": [
-      { "id": "v3", "label": "...", "notes": "...", "author": "...",
-        "date": "YYYY-MM-DD", "hidden": false }
-    ]
-  }
-  ```
-  Human detail (label / author / notes) lives in the **manifest**, not the URL.
-- **"latest" pointer:** the bare `/<project>` serves an auto-generated `index.html` **stub**
-  that meta-refresh / JS-redirects (relative `./vN/`) to the newest **visible** version.
-  The stub is regenerated on every publish/unlist.
-- A directory is treated as a **managed demo iff it contains `project.json`** — this is how
-  the tool distinguishes demos from infrastructure directories.
-
-### Actions
-
-- **Publish a version** — uploads a self-contained HTML export as the next `vN/index.html`,
-  appends a version entry to `project.json`, regenerates the stub, commits.
-- **Adopt** — converts a legacy `index.html`-only demo folder (e.g. `togadesk`) into a
-  managed demo: moves the existing page to `v1/index.html`, writes `project.json`,
-  regenerates the stub.
-- **Remove = unlist only** — sets a `hidden` flag in `project.json`; files are **never
-  deleted** (explicit owner decision).
-- **Edit version metadata** (`apiEditVersion`) — an "Edit" button on each version row opens
-  a modal pre-filled with the version's label, author ("your name"), and notes. Saving
-  commits an **updated `project.json` only** — the version id and the hosted `vN/index.html`
-  are unchanged, and the redirect stub does not depend on this metadata, so **no stub
-  rebuild**. Reuses the existing `isValidVersionId` guard and `postField` length caps (notes
-  cap 2000).
-- **Copy URL** — a button on each project card copies the project's main live URL
-  (`https://demo.togatech.com/<project>`) to the clipboard via `navigator.clipboard`, with a
-  brief "Copied ✓" confirmation.
-- **Copy Claude Design prompt** — one-click copy of the standard self-contained-HTML export
-  prompt (the same prompt documented in [static-demo-hosting](static-demo-hosting.md)).
-- **Create a tab** (`apiCreateTab`, action `create-tab`) — appends a named tab to
-  `tabs.json`. Case-insensitive dedupe; name length-capped 40. Commits `tabs.json` only.
-- **Move a project to a tab** (`apiSetProjectTab`, action `set-project-tab`) — sets/clears a
-  project's `tab` field; empty string = Unsorted (the field is `unset`). Commits that
-  project's `project.json` **only** — tab membership does not affect the redirect stub, so
-  **no stub rebuild**. `apiCreateProject` also accepts an optional `tab`.
-
-The full action set is: `list`, `create-project`, `upload`, `adopt`, `set-latest`,
-`toggle-version`, `edit-version`, `toggle-project`, `create-tab`, `set-project-tab` (plus
-`bootstrap`). `list` also returns the tab list (`{ projects, tabs }`).
-
-### Tab-based organization
-
-Demo projects can be grouped into named **tabs** (e.g. separate Production / Pipeline /
-Sandbox).
-
-- **`tabs.json`** at the repo root holds the ordered tab list — `{"tabs": ["Production",
-  "Pipeline", "Sandbox"]}`. `loadTabs()` returns those three as **defaults when `tabs.json`
-  does not exist yet** (so tabs appear before any are created); the file is only written on
-  the first tab mutation (`create-tab`).
-- Each `project.json` gains an optional **`tab`** field (string). Missing/absent =
-  **"Unsorted"**.
-- **UI:** a filter chip bar (All / each tab / Unsorted / + New tab) with per-tab project
-  counts; clicking a chip filters the list. Each project card has a **Tab `<select>`** to
-  move the project between tabs (on the select's `change`). The New Project modal has a Tab
-  dropdown defaulting to the currently-viewed tab.
-- The **displayed** tab list is the **union** of `tabs.json` order plus any tab names
-  referenced by projects — so removing a tab from `tabs.json` never orphans a project.
-
-### Naming & validation
-
-- Folder names auto-normalized to **lowercase kebab-case**, validated against a kebab regex
-  plus a reserved/excluded list.
-- **`EXCLUDED_FOLDERS`** constant (`design`, `sos`) + `RESERVED_NAMES` are never listed or
-  managed (owner-requested; expected to grow over time).
-
-### Hardening
-
-Input length caps; version-id regex guard; HTML content sniff on upload; security headers;
-no client-facing leakage of GitHub/curl error detail; `declare(strict_types=1)`.
-
-## Access control
-
-**No authentication** — explicit owner product decision. The `/design` URL is unlisted;
-anyone who reaches it can publish or unlist. Do not treat the tool as protected.
-
-## Data model
-
-`project.json` per managed demo (see Versioning model above), plus an optional `tab` string
-field per project (absent = Unsorted). A single repo-root **`tabs.json`** —
-`{"tabs": [...]}` — holds the ordered tab list (defaults to `["Production", "Pipeline",
-"Sandbox"]` until first written). No database.
-
-## Client variations
-
-None — internal/shared design-team tool.
-
-## Gotchas / known issues
-
-- **Contents API inlines only ≤1 MB.** The GitHub Contents API returns an **empty**
-  `content` field for files over ~1 MB. Design exports are routinely multi-MB (the
-  `togadesk` demo is ~4.2 MB), so reading them via the base64 Contents response silently
-  returned empty content — adopt committed a **0-byte `v1/index.html`** (blank page). Fix:
-  `ghReadFile()` uses the **raw media type** (`Accept: application/vnd.github.raw`), which
-  streams files up to 100 MB.
-- **Never hardcode the GitHub token in the tracked `index.php`.** `design/index.php` is
-  git-**tracked**; only `design/.config.php` is git-ignored. Hardcoding a `ghp_` token in
-  `index.php` leaked a live token into pushed `_main` history of `agilantsolutions/forward`.
-  Use `getenv('FORWARD_GITHUB_TOKEN')` (EB env property) or the uncommitted `.config.php`. A
-  leaked token must be **revoked/rotated** — a later commit does not remove it from history.
-  Prefer a **fine-grained PAT** scoped to only the `forward` repo's Contents R/W.
-- **Raise PHP upload limits for multi-MB designs (AL1 / PHP 7.3 specifics).** Default
-  `upload_max_filesize` (~2 MB) rejects real multi-MB design exports. The deploy platform
-  is **PHP 7.3 on 64-bit Amazon Linux 1**, where these values are **not** settable via the
-  `aws:elasticbeanstalk:container:php:phpini` option namespace. Instead a
-  `.ebextensions/php-uploads.config` drops a custom ini at
-  `/etc/php-7.3.d/99-design-uploads.ini` setting `upload_max_filesize=25M`,
-  `post_max_size=30M`, `memory_limit=256M`, `max_execution_time=60`.
-- **Publishing pushes to `_main`** and triggers EB auto-deploy — changes go live in a few
-  minutes; there is no staging step.
-
-## Change history
-
-- 2026-06-23 — Built the Design Demo Admin tool: GitHub-API-only publishing, sequential
-  `/vN` versioning with a `project.json` manifest + auto-generated latest-pointer stub,
-  adopt/unlist actions, `/design` route. Fixed the >1 MB Contents-API empty-content bug
-  (raw media type) and the tracked-token leak (env/`.config.php`). (jcardinal)
-- 2026-06-24 — Added **edit-version** (`apiEditVersion`): an Edit button + modal to revise a
-  version's label/author/notes, committing `project.json` only (no stub rebuild; reuses
-  `isValidVersionId` + length caps). Added a **Copy URL** button on each project card
-  (`navigator.clipboard` → `https://demo.togatech.com/<project>`). Both additive; no new
-  security surface. (jcardinal)
-- 2026-06-25 — Added **tab-based organization**: new repo-root `tabs.json` (ordered tab
-  list, defaults Production/Pipeline/Sandbox until first written via `create-tab`), optional
-  `tab` field on `project.json` (absent = Unsorted), and actions **`create-tab`** /
-  **`set-project-tab`** (`apiCreateProject` accepts an optional `tab`). UI filter chip bar
-  with per-tab counts, per-card Tab select, and a Tab dropdown on the New Project modal. The
-  displayed tab list is the union of `tabs.json` and tabs referenced by projects, so dropping
-  a tab from `tabs.json` never orphans a project. `set-project-tab` commits `project.json`
-  only (no stub rebuild). (jcardinal)
-
-## Related docs
-
-- [Static Demo Hosting](static-demo-hosting.md)
-- [Forwarder Architecture](../architecture.md)