@appsforgood/next-supabase-kit 0.4.2 → 0.4.4

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 0.4.4
+
+- Uplift `frontend-design` and the Design agent from a 2026-09-12 GitHub scan (structure only): name `build` / `review` / `detect`, pick a surface profile, read `DESIGN.md` tokens, tag findings as code-certain or inferred. Do not install a design MCP or canvas CLI. Kit charcoal tokens stay off downstream apps.
+- Add Design `setup` for new repos: scan, then ask what the user needs (who it is for, what they must get done, what this pass should produce). Recommend from the answers, then write style-guide and principles files they asked for. `init` still does not install `DESIGN.md`. Setup may skip screenshots when nothing can render; Design keeps `requiredTools`.
+- Rewrite `ROADMAP.md` Phase 10 as the working queue: playbook parity for `accessibility-wcag` / `testing-qa` / `ship`, optional-skill uplifts, paste-ready handoff. Default `init` stays a relay, not an orchestrator.
+- Uplift `accessibility-wcag` to the playbook bar: WCAG 2.1 AA mapped onto App Router forms and dialogs, keyboard-only pass in the running UI, Reject “contrast looks fine in the screenshot.” Planner, QA, and Design name the skill. Structure from a 2026-09-12 scan; no third-party skill bodies, no required axe.
+- Uplift `testing-qa` to the playbook bar: unit / regression / smoke, list commands actually run, Reject `toBeVisible` as visual proof, RLS tests fail when another user can read the row. Does not replace `browser-qa` or `supabase-auth-rls`.
+
+## 0.4.3
+
+- `doctor` fails if a default agent drops packaged `requiredTools` (QA/Design can no longer drop screenshot tools and still pass).
+- `adapter validate all` validates the IDEs in `.agent-kit/manifest.json` `activated`, not every IDE the kit supports. Named targets still check that one IDE.
+- `loadCatalog` caches per package root so tests and nested installs do not reuse the wrong catalog.
+- `agent-kit guide` prints the local `USER_GUIDE.html` path. GitHub shows that file as source; open it in a browser.
+- `planning` and `testing-qa` name the domain skills they must not replace.
+- Visual P0s: reject left accent bars on selected rows and status wells. Selection is radio/check + tint. Same family as accent-border cards / glow rails, not a second prompt. `USER_GUIDE.html` fail-closed well is a flat tint, not a left stroke.
+- Version Packages keeps a drafted next-version `CHANGELOG.md` heading instead of failing when `package.json` is still on the previous version.
+
 ## 0.4.2
 
 - Uplift default domain skills so they are playbooks, not checklists: `nextjs-app-router` (App Router, async request APIs, `proxy.ts`), `supabase-auth-rls` (SSR clients, `getUser()`, service role, RLS), `postgres-migrations` (RLS in the same change), `owasp-security-review` (Top 10 mapped onto Actions/RLS/SSRF).

package/README.md

@@ -10,7 +10,7 @@ QA does not review user-visible work from code alone. A change is not done until
 npx --yes @appsforgood/next-supabase-kit init --activate all
 ```
 
-Then open **[USER_GUIDE.html](USER_GUIDE.html)** (markdown twin: [USER_GUIDE.md](USER_GUIDE.md)). That guide is how you use the pack.
+Then open **[USER_GUIDE.html](USER_GUIDE.html)** in a browser (markdown twin: [USER_GUIDE.md](USER_GUIDE.md)). GitHub shows the HTML as source; `npx agent-kit guide` prints the local path. That guide is how you use the pack.
 
 ## What you get
 
@@ -23,6 +23,7 @@ Then open **[USER_GUIDE.html](USER_GUIDE.html)** (markdown twin: [USER_GUIDE.md]
 
 ```bash
 npx agent-kit init --activate all
+npx agent-kit guide
 npx agent-kit doctor
 npx agent-kit add skill debug
 npx agent-kit add agent lead-architect

package/UPGRADE.md

@@ -1,5 +1,17 @@
 # Upgrade Guide
 
+## 0.4.3
+
+`0.4.3` does not change installed agent files unless you stripped `requiredTools`. `doctor` now fails that. `adapter validate all` on a Cursor-only install checks Cursor only.
+
+```bash
+npx @appsforgood/next-supabase-kit@0.4.3 update
+npx @appsforgood/next-supabase-kit@0.4.3 doctor
+npx @appsforgood/next-supabase-kit@0.4.3 guide
+```
+
+Open `USER_GUIDE.html` in a browser. GitHub shows it as source.
+
 ## 0.4.2
 
 `0.4.1` is the published simplify catch-up. `0.4.2` rewrites the Next.js and Supabase domain skills. `update` refreshes pristine skill files; local edits win or land in conflicts.

package/USER_GUIDE.html

@@ -220,12 +220,15 @@
       }
 
       .rule {
-        border-left: 4px solid var(--safelight);
         padding: 0.7rem 0.9rem;
-        background: #1a1814;
+        background: #23160f;
         margin: 0 0 1.4rem;
       }
 
+      .rule strong {
+        color: var(--safelight);
+      }
+
       .steps {
         display: grid;
         gap: 0.85rem;
@@ -506,6 +509,14 @@
                 <button class="copy" type="button" data-copy-from="plan-prompt">Copy Planner prompt</button>
               </div>
             </article>
+            <article class="ticket">
+              <header><span>New repo — paste this to Design so it asks what you need</span></header>
+              <pre id="design-setup-prompt">
+Act as design. This is a new repo. Scan what is already here, then ask me what we need to set up: who it is for, what they must get done, and what you should produce. Recommend from my answers. Write the style guide and principles with me before any CSS.</pre>
+              <div class="copy-row">
+                <button class="copy" type="button" data-copy-from="design-setup-prompt">Copy Design setup prompt</button>
+              </div>
+            </article>
           </div>
           <p>
             You should get a named owner (<code>app-engineer</code>, <code>security</code>, <code>design</code>, <code>qa</code>, or <code>copy</code>) and, if
@@ -541,6 +552,10 @@
               <td>It looks wrong</td>
               <td>Design</td>
             </tr>
+            <tr>
+              <td>Style guide / first UI / no DESIGN.md</td>
+              <td>Design (<code>setup</code>)</td>
+            </tr>
             <tr>
               <td>Is this done?</td>
               <td>QA</td>
@@ -583,11 +598,11 @@
             </tr>
             <tr>
               <td><code>frontend-design</code></td>
-              <td>Layout, simple palette, anti-generic UI</td>
+              <td>Setup, build, review, or detect UI. Tokens first. Anti-generic</td>
             </tr>
             <tr>
               <td><code>accessibility-wcag</code></td>
-              <td>Keyboard, contrast, labels</td>
+              <td>Keyboard pass in the running browser. Contrast, labels. Not a screenshot guess</td>
             </tr>
             <tr>
               <td><code>browser-qa</code></td>
@@ -595,7 +610,7 @@
             </tr>
             <tr>
               <td><code>testing-qa</code></td>
-              <td>Unit / regression / smoke only</td>
+              <td>Unit / regression / smoke. List commands run. Not screenshots</td>
             </tr>
             <tr>
               <td><code>product-copy</code></td>
@@ -612,8 +627,9 @@
           </tbody>
         </table>
         <p>
-          QA of a screen always uses <code>browser-qa</code>, not <code>testing-qa</code> alone. Each agent file names the skills it must run, then points at
-          <code>catalog.json</code> for the rest.
+          QA of a screen always uses <code>browser-qa</code>, not <code>testing-qa</code> alone. User-facing screens also run
+          <code>accessibility-wcag</code> (keyboard in the browser, not a contrast guess from the screenshot). Each agent file names the skills it must run,
+          then points at <code>catalog.json</code> for the rest.
         </p>
       </section>
 
@@ -677,17 +693,45 @@ Act as the QA agent. Use the browser-qa skill. Do not review code alone. Open th
           <li>Planner — paste the prompt on ticket 03.</li>
           <li>App engineer — <code>Implement the plan. Smoke the changed route in the browser before you hand off.</code></li>
           <li>Security if data, auth, or secrets changed.</li>
-          <li>Design if the UI changed — <code>Review the running UI from screenshots first. Desktop and mobile. Reject generic AI-looking layout.</code></li>
-          <li>QA — paste the good prompt below.</li>
+          <li>
+            Design if the UI changed —
+            <code
+              >Act as design. Name the mode (setup, build, review, or detect). Review the running UI from screenshots first. Desktop and mobile. Reject generic
+              AI-looking layout.</code
+            >
+            If <code>DESIGN.md</code> is missing, run setup first.
+          </li>
+          <li>QA — paste the good prompt below. For screens, also run <code>accessibility-wcag</code>.</li>
         </ol>
-        <p>Done when QA attaches both frames plus a verdict.</p>
+        <p>Done when QA attaches both frames plus a verdict, and the changed flow passed a keyboard-only check.</p>
         <h3>Auth / RLS</h3>
         <p>
           Planner → App engineer → Security → QA. QA must open login, logout, and denied in the browser. Screenshots still required when the finding is
           user-visible.
         </p>
+        <h3>New repo design setup</h3>
+        <p>After <code>init</code>, before the first product CSS, paste to Design:</p>
+        <pre id="design-setup-flow">
+Act as design. This is a new repo. Scan what is already here, then ask me what we need to set up: who it is for, what they must get done, and what you should produce. Recommend from my answers. Write the style guide and principles with me before any CSS.</pre>
+        <div class="copy-row">
+          <button class="copy" type="button" data-copy-from="design-setup-flow">Copy Design setup prompt</button>
+        </div>
+        <p>
+          Design scans the stack, then asks what you need. Recommendations come from those answers. It writes a short product <code>DESIGN.md</code> and
+          frontend <code>STYLE_GUIDE.md</code> rules only after that. It does not paste this kit’s charcoal desk onto the app. Screenshots wait until there is a
+          screen to capture.
+        </p>
         <h3>UI polish</h3>
-        <p>Design + <code>frontend-design</code> + <code>browser-qa</code>. Desktop and mobile. One happy-path shot is a fail.</p>
+        <p>
+          Design + <code>frontend-design</code> + <code>accessibility-wcag</code> + <code>browser-qa</code>. Name setup, build, review, or detect. Desktop and
+          mobile once a screen exists. One happy-path shot is a fail. A contrast guess from the screenshot is a fail.
+        </p>
+        <h3>Accessibility pass</h3>
+        <p>On any user-facing screen, paste to Design or QA:</p>
+        <pre id="a11y-prompt">Run accessibility-wcag. Open the changed flow. Keyboard-only pass. Do not accept contrast from the screenshot alone.</pre>
+        <div class="copy-row">
+          <button class="copy" type="button" data-copy-from="a11y-prompt">Copy accessibility prompt</button>
+        </div>
         <h3>Copy pass</h3>
         <p>Copy reviews the <em>rendered</em> words in screenshots, not strings in TSX. Run <code>product-copy</code>, then <code>deslop</code> last.</p>
       </section>
@@ -713,8 +757,9 @@ Do not review code alone. Open the app, capture desktop and mobile screenshots,
           <li>Open the changed route with the real auth, role, and data.</li>
           <li>Capture desktop (~1280) and mobile (~390) into <code>qa-evidence/&lt;yyyy-mm-dd&gt;-&lt;slug&gt;/</code>.</li>
           <li><strong>Read the images.</strong> List blockers from what is on screen.</li>
-          <li>Run applicable tests. <code>toBeVisible</code> is not a screenshot.</li>
-          <li>Write <code>notes.md</code> with route, viewports, auth state, verdict.</li>
+          <li>Keyboard-only the changed flow (<code>accessibility-wcag</code>). Do not accept contrast from the screenshot alone.</li>
+          <li>Run applicable tests (<code>testing-qa</code>). List the commands. <code>toBeVisible</code> is not a screenshot.</li>
+          <li>Write <code>notes.md</code> with route, viewports, auth state, keyboard result, commands run, verdict.</li>
         </ol>
         <p>Cursor: built-in browser first. Claude, Codex, Copilot, Antigravity: host browser if present, otherwise:</p>
         <pre id="pw-cmd">
@@ -763,6 +808,10 @@ npx agent-kit update</pre>
               <td>QA finished from the diff</td>
               <td>Reject it. Re-run with the good QA prompt.</td>
             </tr>
+            <tr>
+              <td>GitHub shows this page as code</td>
+              <td>Open <code>USER_GUIDE.html</code> in a browser, or run <code>npx agent-kit guide</code>. GitHub does not render the layout.</td>
+            </tr>
             <tr>
               <td><code>doctor</code> fails the guide</td>
               <td>The screenshot fail-closed sentence must stay in <code>USER_GUIDE.md</code> and this page.</td>

package/USER_GUIDE.md

@@ -23,6 +23,12 @@ Plan this change. Name the owning agent, extra reviewers, and which screenshots
 
 You should get a named owner (`app-engineer`, `security`, `design`, `qa`, or `copy`) and, if the work is user-visible, a desktop + mobile screenshot list.
 
+If this repo has no product `DESIGN.md` yet, also paste to Design:
+
+```text
+Act as design. This is a new repo. Scan what is already here, then ask me what we need to set up: who it is for, what they must get done, and what you should produce. Recommend from my answers. Write the style guide and principles with me before any CSS.
+```
+
 ## How to invoke in each IDE
 
 ### Cursor
@@ -73,6 +79,7 @@ Files: `.antigravity/agent-kit/commands/*.toml`, `.antigravity/runtime-skills/*/
 | Implementation | App engineer |
 | Auth / RLS / secrets | Security |
 | It looks wrong | Design |
+| Style guide / first UI / no DESIGN.md | Design (`setup`) |
 | Is this done? | QA |
 | Landing / CTA words | Copy |
 
@@ -87,15 +94,15 @@ Do not ask one chat to be all six. Planner names the next specialist. It does no
 | `supabase-auth-rls` | Auth, RLS, service role, Storage |
 | `postgres-migrations` | Schema, constraints, RLS in the same change |
 | `owasp-security-review` | Mutations, uploads, SSRF, secrets |
-| `frontend-design` | Layout, simple palette, anti-generic UI |
-| `accessibility-wcag` | Keyboard, contrast, labels |
+| `frontend-design` | Setup, build, review, or detect UI. Tokens first. Anti-generic |
+| `accessibility-wcag` | Keyboard pass in the running browser. Contrast, labels. Not a screenshot guess |
 | `browser-qa` | Any screen. Required for QA of UI |
-| `testing-qa` | Unit / regression / smoke only |
+| `testing-qa` | Unit / regression / smoke. List commands run. Not screenshots |
 | `product-copy` | Headlines and CTAs |
 | `deslop` | Last copy pass. Copy always runs this |
 | `ship` | Release, env, rollback |
 
-QA of a screen always uses `browser-qa`, not `testing-qa` alone. Each agent file names the skills it must run, then points at `catalog.json` for the rest.
+QA of a screen always uses `browser-qa`, not `testing-qa` alone. User-facing screens also run `accessibility-wcag` (keyboard in the browser, not a contrast guess from the screenshot). Each agent file names the skills it must run, then points at `catalog.json` for the rest.
 
 ## Standard workflows
 
@@ -104,18 +111,36 @@ QA of a screen always uses `browser-qa`, not `testing-qa` alone. Each agent file
 1. **Planner** — paste: `Plan this change. Name the owning agent, extra reviewers, and which screenshots QA must capture. Do not write code.`
 2. **App engineer** — paste: `Implement the plan. Smoke the changed route in the browser before you hand off.`
 3. **Security** if data/auth/secrets changed.
-4. **Design** if the UI changed — paste: `Review the running UI from screenshots first. Desktop and mobile. Reject generic AI-looking layout.`
-5. **QA** — paste: `Do not review code alone. Open the app, capture desktop and mobile screenshots, read the images, then give accept / accept-with-nits / reject.`
+4. **Design** if the UI changed — paste: `Act as design. Name the mode (setup, build, review, or detect). Review the running UI from screenshots first. Desktop and mobile. Reject generic AI-looking layout.` If `DESIGN.md` is missing, run setup first.
+5. **QA** — paste: `Do not review code alone. Open the app, capture desktop and mobile screenshots, read the images, then give accept / accept-with-nits / reject.` For screens, also run `accessibility-wcag`.
 
-Done when QA attaches `qa-evidence/<date>-<slug>/desktop.png` and `mobile.png` plus a verdict.
+Done when QA attaches `qa-evidence/<date>-<slug>/desktop.png` and `mobile.png` plus a verdict, and the changed flow passed a keyboard-only check.
 
 ### Auth / RLS change
 
 Planner → App engineer → Security → QA. QA must open login/logout/denied in the browser and still run tests. Screenshots required when the finding is user-visible.
 
+### New repo design setup
+
+After `init`, before the first product CSS, paste to Design:
+
+```text
+Act as design. This is a new repo. Scan what is already here, then ask me what we need to set up: who it is for, what they must get done, and what you should produce. Recommend from my answers. Write the style guide and principles with me before any CSS.
+```
+
+Design scans the stack, then asks what you need. Recommendations come from those answers. It writes a short product `DESIGN.md` and frontend `STYLE_GUIDE.md` rules only after that. It does not paste this kit’s charcoal desk onto the app. Screenshots wait until there is a screen to capture.
+
 ### UI polish
 
-Design + `frontend-design` + `browser-qa`. Desktop and mobile required. One happy-path shot is a fail.
+Design + `frontend-design` + `accessibility-wcag` + `browser-qa`. Name setup, build, review, or detect. Desktop and mobile required once a screen exists. One happy-path shot is a fail. A contrast guess from the screenshot is a fail.
+
+### Accessibility pass
+
+On any user-facing screen, paste to Design or QA:
+
+```text
+Run accessibility-wcag. Open the changed flow. Keyboard-only pass. Do not accept contrast from the screenshot alone.
+```
 
 ### Copy pass
 
@@ -141,8 +166,9 @@ Steps the QA agent must follow:
 2. Open the changed route with the real auth/role/data state.
 3. Capture desktop (~1280) and mobile (~390) into `qa-evidence/<yyyy-mm-dd>-<slug>/`.
 4. **Read the images.** List blockers from what is on screen.
-5. Run applicable tests.
-6. Write `notes.md` with route, viewports, auth state, verdict.
+5. Keyboard-only the changed flow (`accessibility-wcag`). Do not accept contrast from the screenshot alone.
+6. Run applicable tests (`testing-qa`). List the commands. `toBeVisible` is not a screenshot.
+7. Write `notes.md` with route, viewports, auth state, keyboard result, commands run, verdict.
 
 Cursor: use the built-in browser first. Claude / Codex / Copilot / Antigravity: use the host browser if present, otherwise Playwright:
 
@@ -179,5 +205,6 @@ Pristine files refresh. Local edits win or land in `.agent-kit/conflicts/`. Do n
 | Skill not triggering | Mention the skill name (`browser-qa`) or `@` it in Cursor. |
 | No browser in Copilot / Codex | Use the Playwright commands in `browser-qa`. |
 | QA finished from the diff | Reject it. Re-run with the good QA prompt above. |
+| GitHub shows `USER_GUIDE.html` as code | Open the file in a browser. Run `npx agent-kit guide` to print the path. GitHub does not render the layout. |
 | `doctor` fails USER_GUIDE | The screenshot fail-closed sentence must stay in this file. |
 | Still have `QUALITY_GATES.md` / `COUNCIL.md` | Expected. `update` does not delete them. `doctor` lists leftovers. |

package/agents/design/agent.md

@@ -1,6 +1,6 @@
 ---
 name: design
-description: Use for UI quality, accessibility, and anti-generic layout. Critique screenshots first, then code.
+description: Use for UI quality, accessibility, and anti-generic layout. Name setup, build, review, or detect. New repos: ask what they need, then principles, before CSS. Critique screenshots first, then code.
 tools: [repo, edit, browser, screenshot, image-review]
 requiredTools: [browser, screenshot, image-review]
 ---
@@ -9,25 +9,33 @@ requiredTools: [browser, screenshot, image-review]
 
 Review and improve user-facing UI. Start from screenshots. Reject a single happy-path shot and reject generic AI-looking layout.
 
+Name the **mode** (`setup`, `build`, `review`, or `detect`) and, except setup, the **surface** (`landing`, `app-chrome`, `inside-design-system`, or `kit-html`) before changing CSS. Detect means audit only — no edits.
+
+**Setup** when `DESIGN.md` is missing or TBD, the user asked to set up design / a style guide / principles, or this is first UI work in a fresh install. Scan the repo, then **ask what they need** — who it is for, what they must get done, what this pass should produce. Follow up if answers are vague. Recommend principles from those answers, then write only the style-guide files they asked for. No CSS until they ask to build. Screenshots are not required if nothing can render yet. Do not drop `requiredTools`.
+
 This kit’s HTML (especially `USER_GUIDE.html`) is an assignment desk, not a SaaS landing page. First screen: named specialists, the fail-closed screenshot rule, and a pasteable prompt. Use `frontend-design` kit tokens: charcoal paper `#10100e`, ink `#eceae4`, safelight `#ff5a2a` only for required QA, Helvetica Neue + mono, 2px radius, no gradients, no card soup. Downstream product screens get their own 4–6 tokens — do not paste the kit desk onto an app.
 
-Public words on a screen hand to Copy. Copy finishes with `deslop`. You restyle leftover visual P0s.
+Read `DESIGN.md` when it exists. Public words on a screen hand to Copy. Copy finishes with `deslop`. You restyle leftover visual P0s. QA owns accept / accept-with-nits / reject.
 
 ## Use when
 
-Screens, components, layout, visual design, responsive behavior, or “it looks wrong.”
+Screens, components, layout, visual design, responsive behavior, “it looks wrong,” or first-run design setup on a new repo.
 
 ## Tools
 
 Allowed: `repo`, `edit`, `browser`, `screenshot`, `image-review`.  
-Required: open the running UI, capture desktop (~1280) and mobile (~390), and write findings from the images.
+Required for `build`, `review`, and `detect`: open the running UI, capture desktop (~1280) and mobile (~390), and write findings from the images. Detect still captures when a server is up; if nothing can render, mark visual findings inferred. Setup may skip capture when nothing can render yet.
 
 ## Skills
 
-`frontend-design`, `accessibility-wcag`, `browser-qa`. Visual P0 list lives in `deslop`; you fix pixels, Copy does not.
+`frontend-design`, `accessibility-wcag`, `browser-qa`. Visual P0 list lives in `deslop`; you fix pixels, Copy does not. Optional `ui-polish` is a later spacing/state pass, not a second design system. On user-visible UI, run `accessibility-wcag` — keyboard in the running browser. `frontend-design` does not replace it.
 
 Available skills: `catalog.json` and the skill table in `USER_GUIDE.md`. Start with the skills named above. Use another listed skill when this job needs it.
 
+## Review output
+
+For `review` and `detect`, return a severity table (P0 / P1 / P2) with where it showed up and whether it is code-certain or inferred. Then, unless detect, fix P0s.
+
 ## Done when
 
-Desktop and mobile screenshots were captured and read. Blockers (overlap, contrast, clipped text, missing tap targets, generic gradient/card soup) are fixed or explicitly accepted. One screenshot is not enough.
+Mode was named. Setup asked what they need and recorded the answers they asked to keep. No unsolicited CSS. For other modes, a surface was named and desktop and mobile screenshots were captured and read. Blockers (overlap, contrast, clipped text, missing tap targets, generic gradient/card soup, left-edge selection rails) are fixed or explicitly accepted. One screenshot is not enough. On screens that can render, `accessibility-wcag` had a keyboard-only pass or remaining gaps are named. Detect ends with the table and no edits.

package/agents/qa/agent.md

@@ -31,7 +31,9 @@ Available skills: `catalog.json` and the skill table in `USER_GUIDE.md`. Start w
 - One desktop screenshot of the happy path.
 - Playwright `toBeVisible` with no image.
 - Skipping mobile, or skipping auth/empty/error when those states exist.
+- “Contrast looks fine in the screenshot” without a keyboard-only pass on the changed flow (`accessibility-wcag`).
+- “Tests pass” with no command list (`testing-qa`).
 
 ## Done when
 
-You opened the running app, captured desktop and mobile screenshots, **read the images**, ran applicable tests, and wrote accept / accept-with-nits / reject with image paths under `qa-evidence/`.
+You opened the running app, captured desktop and mobile screenshots, **read the images**, ran applicable tests **and listed the commands**, and wrote accept / accept-with-nits / reject with image paths under `qa-evidence/`. For screens, `accessibility-wcag` ran: a keyboard-only pass on the changed flow, not a screenshot guess.