@appsforgood/next-supabase-kit 0.4.0 → 0.4.2

package/USER_GUIDE.md

@@ -1,6 +1,6 @@
 # User Guide
 
-How to use the agents and skills in this repo.
+How to use the agents and skills in this repo. Open **[USER_GUIDE.html](USER_GUIDE.html)** to read this as a designed page — that is the copy and layout to judge.
 
 **Agent** = who you ask. **Skill** = the workflow they follow. **Tool** = what they must use. For QA and UI, that tool is a **live browser plus screenshots**, not a file diff.
 
@@ -76,25 +76,26 @@ Files: `.antigravity/agent-kit/commands/*.toml`, `.antigravity/runtime-skills/*/
 | Is this done? | QA |
 | Landing / CTA words | Copy |
 
-Do not ask one chat to be all six.
+Do not ask one chat to be all six. Planner names the next specialist. It does not run the other agents.
 
 ## Which skill do I use?
 
 | Skill | Use when |
 | --- | --- |
-| `planning` | Ambiguous work; pick an owner |
-| `nextjs-app-router` | Routes, Server Components, actions |
-| `supabase-auth-rls` | Auth, RLS, service role |
-| `postgres-migrations` | Schema and migrations |
-| `owasp-security-review` | Mutations, uploads, secrets |
-| `frontend-design` | Layout, hierarchy, anti-generic UI |
+| `planning` | Ambiguous work; pick an owner and which skill they run |
+| `nextjs-app-router` | App Router, Server vs Client, actions, `proxy.ts` |
+| `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 |
 | `browser-qa` | Any screen. Required for QA of UI |
 | `testing-qa` | Unit / regression / smoke only |
 | `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.
+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.
 
 ## Standard workflows
 
@@ -118,7 +119,7 @@ Design + `frontend-design` + `browser-qa`. Desktop and mobile required. One happ
 
 ### Copy pass
 
-Copy agent reviews **rendered** screenshots, not just strings in TSX.
+Copy reviews **rendered** screenshots, not just strings in TSX. Run `product-copy`, then **`deslop` last**. Do not hand off after the first draft.
 
 ## QA screenshot loop
 
@@ -179,3 +180,4 @@ Pristine files refresh. Local edits win or land in `.agent-kit/conflicts/`. Do n
 | 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. |
 | `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/app-engineer/agent.md

@@ -23,6 +23,10 @@ Code-only “it should work” is incomplete for anything the user can see or cl
 
 `nextjs-app-router`, `supabase-auth-rls`, `postgres-migrations`.
 
+Run those skills. Do not treat a small route, form, or table as exempt.
+
+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.
+
 ## Handoff
 
 Security reviews auth/data/secret changes. Design reviews user-facing screens. QA always reviews behavior or UI changes with `browser-qa`.

package/agents/copy/agent.md

@@ -1,6 +1,6 @@
 ---
 name: copy
-description: Use for public-facing or conversion copy. Review the rendered words in screenshots, not just strings in TSX.
+description: Use for public-facing or conversion copy. Review the rendered words in screenshots, not just strings in TSX. Always finish with the deslop skill.
 tools: [repo, edit, screenshot, image-review]
 requiredTools: [repo, image-review]
 ---
@@ -9,6 +9,8 @@ requiredTools: [repo, image-review]
 
 Write and review headlines, CTAs, empty states, and onboarding copy. Approve words as they appear on screen.
 
+For this kit, copy must name specialists and ask the reader to paste a prompt or run `init`. Headlines that could sell any copilot fail. Public HTML is not done until the rendered screenshot shows the key line and CTA without truncation.
+
 ## Use when
 
 Landing pages, CTAs, positioning, empty states, pricing, or conversion copy.
@@ -20,8 +22,19 @@ Required: read the repo and review rendered copy from screenshots when the surfa
 
 ## Skills
 
-`product-copy`, `frontend-design`.
+`product-copy` first, then `frontend-design` if the words live on a screen. **`deslop` last. Always.** Do not hand off after `product-copy` alone.
+
+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.
+
+## End run
+
+1. Write or edit with `product-copy`.
+2. Read the rendered screenshot (desktop and mobile when the surface is a page).
+3. Run `deslop`. Fix writing tells. List leftover visual P0s for Design.
+4. Run `deslop` a second time on your own rewrite.
+
+If you skip step 3, the work is not done.
 
 ## Done when
 
-Copy is specific to this product, claims are not invented, and the rendered screenshot shows the CTA and key line without truncation or hierarchy collapse.
+Copy is specific to this product, claims are not invented, `deslop` has been run as the last pass, and the rendered screenshot shows the CTA and key line without truncation or hierarchy collapse.

package/agents/design/agent.md

@@ -9,6 +9,10 @@ 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.
 
+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.
+
 ## Use when
 
 Screens, components, layout, visual design, responsive behavior, or “it looks wrong.”
@@ -20,7 +24,9 @@ Required: open the running UI, capture desktop (~1280) and mobile (~390), and wr
 
 ## Skills
 
-`frontend-design`, `accessibility-wcag`, `browser-qa`.
+`frontend-design`, `accessibility-wcag`, `browser-qa`. Visual P0 list lives in `deslop`; you fix pixels, Copy does not.
+
+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.
 
 ## Done when
 

package/agents/optional/deploy/agent.md

@@ -9,4 +9,10 @@ requiredTools: [repo]
 
 Confirm release order, env vars, and rollback. Use the `ship` skill.
 
+## Skills
+
+`ship`.
+
+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.
+
 Add with `agent-kit add agent deploy`.

package/agents/optional/docs/agent.md

@@ -9,4 +9,8 @@ requiredTools: [repo]
 
 Keep `USER_GUIDE.md`, `AGENTS.md`, and project docs accurate. Do not invent product claims.
 
+## Skills
+
+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.
+
 Add with `agent-kit add agent docs`.

package/agents/optional/lead-architect/agent.md

@@ -9,4 +9,12 @@ requiredTools: [repo]
 
 Map affected layers and preserve behavioral contracts. Do not implement unless asked.
 
+## Skills
+
+`planning`.
+
+You name layers and tradeoffs. You do not run the other agents.
+
+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.
+
 Add with `agent-kit add agent lead-architect` only when the change spans data, auth, and presentation.

package/agents/optional/research/agent.md

@@ -9,4 +9,8 @@ requiredTools: [repo]
 
 Inventory public agent/skill patterns. Extract structure only. Do not re-import an operating system.
 
+## Skills
+
+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.
+
 Add with `agent-kit add agent research`.

package/agents/planner/agent.md

@@ -19,6 +19,14 @@ Allowed: `repo` (read and search only).
 Required: read the repo before naming owners.  
 Do not edit product code.
 
+## Skills
+
+`planning`.
+
+You name the owner and reviewers. You do not run the other agents.
+
+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.
+
 ## Handoff
 
 Name one owner from: `app-engineer`, `security`, `design`, `qa`, `copy`.  

package/agents/qa/agent.md

@@ -23,6 +23,8 @@ Hard fail if the only evidence is a file diff.
 
 `browser-qa`, `testing-qa`, `accessibility-wcag`.
 
+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.
+
 ## Must not accept
 
 - “Reviewed `page.tsx`; layout looks correct.”

package/agents/security/agent.md

@@ -23,6 +23,8 @@ RLS/SQL-only findings may stay code + tests.
 
 `owasp-security-review`, `supabase-auth-rls`, `postgres-migrations`.
 
+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.
+
 ## Done when
 
 Access control is enforced in Postgres or the server, not only in the UI. Login, redirect, and denied states were checked in the browser when they exist. Secrets stay server-only.

package/catalog.json

@@ -13,6 +13,7 @@
     "browser-qa",
     "testing-qa",
     "product-copy",
+    "deslop",
     "ship"
   ],
   "optionalSkills": ["ui-polish", "docs", "upgrade", "debug"],

package/dist/index.js

@@ -317,7 +317,7 @@ function generateAntigravityCommands(cwd, force, collector) {
     {
       name: "copy",
       description: "Review rendered conversion copy.",
-      prompt: "Act as the copy agent. Review the rendered words in screenshots, not just strings in source."
+      prompt: "Act as the copy agent. Review the rendered words in screenshots, not just strings in source. Run product-copy first, then deslop last. Always."
     },
     {
       name: "test",
@@ -550,6 +550,13 @@ function validatePackage() {
   } else {
     findings.push({ level: "pass", area: "package", message: "USER_GUIDE.md includes the screenshot rule." });
   }
+  if (!existsSync6(join5(cwd, "USER_GUIDE.html"))) {
+    findings.push({ level: "fail", area: "package", message: "USER_GUIDE.html is missing." });
+  } else if (!readFileSync6(join5(cwd, "USER_GUIDE.html"), "utf8").includes("Do not review code alone")) {
+    findings.push({ level: "fail", area: "package", message: "USER_GUIDE.html dropped the screenshot fail-closed sentence." });
+  } else {
+    findings.push({ level: "pass", area: "package", message: "USER_GUIDE.html includes the screenshot rule." });
+  }
   if (!existsSync6(join5(cwd, "skills/browser-qa/SKILL.md"))) {
     findings.push({ level: "fail", area: "package", message: "skills/browser-qa/SKILL.md is missing." });
   }
@@ -559,6 +566,15 @@ function validatePackage() {
 // src/install/doctor.ts
 import { existsSync as existsSync7, readFileSync as readFileSync7 } from "fs";
 import { join as join6 } from "path";
+var LEGACY_LEFTOVER_PATHS = [
+  "AGENT_ROSTER.md",
+  "COUNCIL.md",
+  "SKILLS.md",
+  "QUALITY_GATES.md",
+  "ASSISTANT_ADAPTERS.md",
+  ".agent-kit/agent-roster.json",
+  ".agent-kit/orchestrator.json"
+];
 function summarize(findings) {
   return {
     pass: findings.filter((item) => item.level === "pass").length,
@@ -570,6 +586,9 @@ function read(cwd, relative2) {
   const path = join6(cwd, relative2);
   return existsSync7(path) ? readFileSync7(path, "utf8") : null;
 }
+function listLegacyLeftovers(cwd) {
+  return LEGACY_LEFTOVER_PATHS.filter((relative2) => existsSync7(join6(cwd, relative2)));
+}
 function createDoctorReport(cwd) {
   const catalog = loadCatalog();
   const findings = [];
@@ -589,6 +608,18 @@ function createDoctorReport(cwd) {
   } else {
     findings.push({ level: "pass", area: "docs", message: "USER_GUIDE.md includes the screenshot fail-closed rule." });
   }
+  const htmlGuide = read(cwd, "USER_GUIDE.html");
+  if (!htmlGuide) {
+    findings.push({ level: "fail", area: "docs", message: "USER_GUIDE.html is missing. Run agent-kit init." });
+  } else if (!htmlGuide.includes("Do not review code alone") || !htmlGuide.includes('data-view="user-guide"')) {
+    findings.push({
+      level: "fail",
+      area: "docs",
+      message: "USER_GUIDE.html dropped the screenshot fail-closed rule or assignment-desk layout."
+    });
+  } else {
+    findings.push({ level: "pass", area: "docs", message: "USER_GUIDE.html is the visual field guide." });
+  }
   const qaSkill = read(cwd, ".cursor/skills/browser-qa/SKILL.md") ?? read(cwd, "skills/browser-qa/SKILL.md");
   if (!qaSkill) {
     findings.push({ level: "fail", area: "skills", message: "browser-qa skill is missing." });
@@ -610,6 +641,22 @@ function createDoctorReport(cwd) {
       findings.push({ level: "pass", area: "agents", message: `${id} declares tools.` });
     }
   }
+  const leftovers = listLegacyLeftovers(cwd);
+  if (leftovers.length > 0) {
+    const preview = leftovers.slice(0, 6).join(", ");
+    const extra = leftovers.length > 6 ? `, +${leftovers.length - 6} more` : "";
+    findings.push({
+      level: "warn",
+      area: "legacy",
+      message: `0.3 leftover files are still here: ${preview}${extra}. 0.4 uses AGENTS.md + USER_GUIDE. update never deletes these.`
+    });
+  } else {
+    findings.push({
+      level: "pass",
+      area: "legacy",
+      message: "No 0.3 council leftover files detected."
+    });
+  }
   return {
     findings,
     summary: summarize(findings),
@@ -623,14 +670,15 @@ import { join as join8 } from "path";
 
 // src/config/defaults.ts
 var PACKAGE_NAME = "@appsforgood/next-supabase-kit";
-var PACKAGE_VERSION = "0.4.0";
-var ROOT_DOCS = ["AGENTS.md", "USER_GUIDE.md"];
+var PACKAGE_VERSION = "0.4.2";
+var ROOT_DOCS = ["AGENTS.md", "USER_GUIDE.md", "USER_GUIDE.html"];
 var CURSOR_RULE_FILE = {
   source: "assistant-adapters/cursor-agent-kit.mdc",
   target: ".cursor/rules/cursor-agent-kit.mdc"
 };
 var CLAUDE_TEMPLATE = "templates/next-supabase/CLAUDE.md";
 var USER_GUIDE_SOURCE = "USER_GUIDE.md";
+var USER_GUIDE_HTML_SOURCE = "USER_GUIDE.html";
 var AGENTS_DOC_SOURCE = "templates/next-supabase/AGENTS.md";
 
 // src/install/ide-activate.ts
@@ -701,6 +749,7 @@ function listManagedAssets(packageRoot, options = {}) {
   const assets = [
     { target: "AGENTS.md", sourcePath: join7(packageRoot, AGENTS_DOC_SOURCE), category: "root-doc" },
     { target: "USER_GUIDE.md", sourcePath: join7(packageRoot, USER_GUIDE_SOURCE), category: "root-doc" },
+    { target: "USER_GUIDE.html", sourcePath: join7(packageRoot, USER_GUIDE_HTML_SOURCE), category: "root-doc" },
     { target: CURSOR_RULE_FILE.target, sourcePath: join7(packageRoot, CURSOR_RULE_FILE.source), category: "adapter" }
   ];
   const activated = new Set(options.activated ?? ["cursor"]);
@@ -728,8 +777,10 @@ function initProject(options) {
   const templateHashes = {};
   const agentsDoc = readFileSync8(join8(packageRoot, AGENTS_DOC_SOURCE), "utf8");
   const userGuide = readFileSync8(join8(packageRoot, USER_GUIDE_SOURCE), "utf8");
+  const userGuideHtml = readFileSync8(join8(packageRoot, USER_GUIDE_HTML_SOURCE), "utf8");
   templateHashes["AGENTS.md"] = sha256(agentsDoc);
   templateHashes["USER_GUIDE.md"] = sha256(userGuide);
+  templateHashes["USER_GUIDE.html"] = sha256(userGuideHtml);
   recordCopy(
     result,
     copyTextWithConflict(join8(packageRoot, AGENTS_DOC_SOURCE), cwd, "AGENTS.md", {
@@ -744,6 +795,13 @@ function initProject(options) {
       conflictRoot: join8(cwd, ".agent-kit", "conflicts")
     })
   );
+  recordCopy(
+    result,
+    copyTextWithConflict(join8(packageRoot, USER_GUIDE_HTML_SOURCE), cwd, "USER_GUIDE.html", {
+      force,
+      conflictRoot: join8(cwd, ".agent-kit", "conflicts")
+    })
+  );
   if (options.legacyDocs) {
     const legacyRoot = join8(packageRoot, "templates", stack);
     const legacyDocs = ["SPEC.md", "DECISIONS.md", "DESIGN.md", "SECURITY.md", "TESTING.md", "QUALITY_GATES.md"];
@@ -940,7 +998,8 @@ function updateProject(options) {
       files: files2,
       libraryFoldersRefreshed: [],
       manifestPath: ".agent-kit/manifest.json",
-      summary: summarize2(files2)
+      summary: summarize2(files2),
+      leftoverDocs: listLegacyLeftovers(cwd)
     };
   }
   const packageRoot = findPackageRoot();
@@ -993,7 +1052,7 @@ function updateProject(options) {
       packageVersion: PACKAGE_VERSION,
       schemaVersion: 3,
       updatedAt: (/* @__PURE__ */ new Date()).toISOString(),
-      docs: ["AGENTS.md", "USER_GUIDE.md"],
+      docs: ["AGENTS.md", "USER_GUIDE.md", "USER_GUIDE.html"],
       assetHashes: nextHashes
     };
     writeText(join9(cwd, ".agent-kit", "manifest.json"), `${JSON.stringify(next, null, 2)}
@@ -1010,7 +1069,8 @@ function updateProject(options) {
     files,
     libraryFoldersRefreshed: [],
     manifestPath: ".agent-kit/manifest.json",
-    summary: summarize2(files)
+    summary: summarize2(files),
+    leftoverDocs: listLegacyLeftovers(cwd)
   };
 }
 
@@ -1053,14 +1113,14 @@ function fail(message) {
 // src/cli/index.ts
 var program = new Command();
 program.name("agent-kit").description("Install agents, skills, and a user guide. QA must review screenshots, not code alone.").version(PACKAGE_VERSION);
-program.command("init").description("Install AGENTS.md, USER_GUIDE.md, and native IDE agents/skills.").option("--stack <stack>", "Stack profile", "next-supabase").option("--activate <targets...>", "IDE surfaces: cursor, claude, codex, copilot, antigravity, all").option("--legacy-docs", "Also copy leftover living-doc templates").option("--force", "Overwrite customized files").option("--json", "Machine-readable output").option("--dry-run", "Show what would be written").action((options) => {
+program.command("init").description("Install AGENTS.md, USER_GUIDE.md, USER_GUIDE.html, and native IDE agents/skills.").option("--stack <stack>", "Stack profile", "next-supabase").option("--activate <targets...>", "IDE surfaces: cursor, claude, codex, copilot, antigravity, all").option("--legacy-docs", "Also copy leftover living-doc templates").option("--force", "Overwrite customized files").option("--json", "Machine-readable output").option("--dry-run", "Show what would be written").action((options) => {
   if (options.dryRun) {
     if (options.json) {
-      printJson({ dryRun: true, wouldWrite: ["AGENTS.md", "USER_GUIDE.md", ".cursor/agents/", ".cursor/skills/"] });
+      printJson({ dryRun: true, wouldWrite: ["AGENTS.md", "USER_GUIDE.md", "USER_GUIDE.html", ".cursor/agents/", ".cursor/skills/"] });
       return;
     }
     heading("init dry-run");
-    line("Would write AGENTS.md, USER_GUIDE.md, and native IDE agent/skill files.");
+    line("Would write AGENTS.md, USER_GUIDE.md, USER_GUIDE.html, and native IDE agent/skill files.");
     return;
   }
   const result = initProject({
@@ -1078,7 +1138,7 @@ program.command("init").description("Install AGENTS.md, USER_GUIDE.md, and nativ
   line(`copied: ${result.copied.length}`);
   line(`unchanged: ${result.unchanged.length}`);
   line(`conflicts: ${result.conflicts.length}`);
-  detail("Read USER_GUIDE.md next.");
+  detail("Open USER_GUIDE.html next.");
 });
 program.command("update").description("Refresh pristine installed files. Local edits win or become conflicts.").option("--force", "Overwrite customized files").option("--dry-run", "Preview only").option("--json", "Machine-readable output").action((options) => {
   const result = updateProject({ cwd: process.cwd(), force: Boolean(options.force), dryRun: Boolean(options.dryRun) });
@@ -1090,6 +1150,9 @@ program.command("update").description("Refresh pristine installed files. Local e
   line(
     `created ${result.summary.created}, updated ${result.summary.updated}, kept-local ${result.summary["kept-local"]}, conflicts ${result.summary.conflict}`
   );
+  if (result.leftoverDocs.length > 0) {
+    detail(`Left in place (not deleted): ${result.leftoverDocs.join(", ")}. Run doctor for the 0.4 layout.`);
+  }
 });
 var add = program.command("add").description("Add an optional agent or skill.");
 add.command("skill <name>").description("Install one skill into .cursor/skills").option("--force", "Overwrite").option("--dry-run", "Preview").option("--json", "Machine-readable output").action((name, options) => {
@@ -1110,7 +1173,7 @@ add.command("agent <name>").description("Install one agent into .cursor/agents a
   line(`${result.action} ${result.target}`);
   if (!options.dryRun) detail(`Available agents: ${listAgents().join(", ")}`);
 });
-program.command("doctor").description("Check that agents, skills, and the screenshot QA rule are present.").option("--json", "Machine-readable output").action((options) => {
+program.command("doctor").description("Check agents, skills, the screenshot QA rule, and leftover 0.3 council files.").option("--json", "Machine-readable output").action((options) => {
   const report2 = createDoctorReport(process.cwd());
   if (options.json) {
     printJson(report2);