@appsforgood/next-supabase-kit 0.1.4 → 0.1.6

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.1.6
+
+- Added a repo-native UI improvement harness with command-style prompts, deterministic detector checklist, acceptance rubric, portable runtime skill, and focused Antigravity UI commands.
+- Wired UI audit, polish, layout cleanup, responsive cleanup, accessibility, distinctiveness, screenshot critique, and browser QA workflows into roster routing, docs, templates, package validation, and example snapshots.
+
+## 0.1.5
+
+- Added computed **Agentic Engineering Level** (L3–L6) in Agent Office and setup wizard: iceberg strip, climb checklist, `/api/state` payload, and `POST /api/agentic-level/refresh`.
+- Added [`src/studio/agentic-level.ts`](src/studio/agentic-level.ts), [`schemas/agentic-level.schema.json`](schemas/agentic-level.schema.json), and maintainer-profile L6 signals for kit source repos.
+- Extended setup wizard with adapter validate chip on IDE activation, audit-readiness vs Agentic level copy, and `LOOP_CODING.md` eval-loop next steps on complete.
+- Added [`research/summaries/agentic-engineering-maturity-levels.md`](research/summaries/agentic-engineering-maturity-levels.md) and cross-links from `DOCS.md`, `HANDOVER.md`, and `LOOP_CODING.md`.
+
 ## 0.1.4
 
 - Added true multi-agent IDE activation for **Cursor** (`.cursor/agents/*.md`, `.cursor/skills/*/SKILL.md`, scoped rules) and **Codex** (`.codex/agents/*.toml` with model routing effort) via `agent-kit init --activate cursor|codex`.

package/DOGFOOD.md

@@ -34,6 +34,15 @@ Mode: read-only audit; no downstream files were modified.
 - Assistant adapters and upgrade lifecycle still need real activation/dogfood evidence after publication.
 - Reference-led design critique still needs a real UI change dogfood pass with screenshots or equivalent visual evidence.
 
+## 2026-07-02 Publish Verification And Self-Install Snapshot
+
+Date: 2026-07-02
+CLI source: public npm registry (`@appsforgood/next-supabase-kit`, published) plus local `src/` for the self-install.
+Mode: post-publish verification against the live registry, and dogfooding the kit into this repo's own root.
+
+- `node scripts/post-publish-verify.mjs` against the published package passed: registry visibility confirmed, `npx` doctor ok, clean temp `init` installed 23 files, and `audit --json --min-readiness baseline-setup` returned 0 failures (readiness `baseline-setup`).
+- This repo now dogfoods its own kit at the root: `agent-kit init` installed the root docs, `.agent-kit/`, and Cursor rules; project context, council session, and overrides were filled with real evidence; `agent-kit audit --min-readiness best-practice-candidate` passes with 0 warnings and 0 failures.
+
 ## 2026-06-07 Agent Studio Dogfood Snapshot
 
 Date: 2026-06-07
@@ -119,3 +128,18 @@ Covered by `tests/update.test.ts`.
 - Activate at least one assistant adapter in a real project and record whether the chosen tool loads the canonical council instructions.
 - Apply the reference-led design critique gate to one real frontend change with desktop/mobile screenshot evidence.
 - After public publish, run `npm run publish:verify` to verify registry visibility, public `npx doctor`, clean temp `init`, and `audit --json` with zero failures.
+
+## BaseRepo Maintainer Dogfood Policy
+
+Date: 2026-06-17
+Policy: **gitignored local overlay + bootstrap script** (not committed to kit source)
+
+| Item | Detail |
+| --- | --- |
+| Bootstrap | `npm run dogfood:init` runs `agent-kit init --stack next-supabase --activate cursor --activate codex` against the repo root |
+| Gitignore | `.agent-kit/`, `.codex/`, init-generated council docs at repo root, and local pack tarballs — see `.gitignore` and [DOCS.md](DOCS.md#maintainer-dogfood) |
+| Validation | `node dist/index.js adapter validate cursor\|codex` after bootstrap |
+| Release evidence | [MAINTAINER_RELEASE.md](MAINTAINER_RELEASE.md) session checklist; loop patterns in [LOOP_CODING.md](LOOP_CODING.md) |
+| Rationale | Kit source stays in `templates/` and tracked maintainer docs; overlay proves Tier B activation without polluting commit history |
+
+This policy closes the gap where the kit shipped Level 5 IDE surfaces but BaseRepo maintainers operated at Level 4 day-to-day.

package/LOOP_CODING.md

@@ -0,0 +1,107 @@
+# Loop Coding
+
+Loop coding means the agent repeats **plan → act → check → fix** until a stop condition, instead of finishing in one chat turn. The Agent Kit is opinionated about **which loops are safe** and **which checkpoints must stay in place**.
+
+This document describes loop types, kit-safe patterns, and limits. It is the canonical reference for eval-driven development with `@appsforgood/next-supabase-kit`.
+
+## Loop Types
+
+| Loop type | What it means | Kit-safe version |
+| --- | --- | --- |
+| **Agent loop** | Same agent iterates on feedback until done | Use scoped prompts (for example `.agent-kit/prompts/implement-feature.md`); review each turn; do not remove Security Reviewer or QA gates |
+| **Eval-driven loop** | Code changes until **tests, audit, or evals pass** | `npm test` + `agent-kit audit` + CI — BaseRepo uses `npm run release:check` as the maintainer merge gate |
+| **Self-improving loop** | Agent critiques its own output and revises | Manual: delegate to `@qa-engineer` or run tests between passes; **avoid fully unsupervised self-critique on auth, RLS, or release tooling** |
+| **Council / team loop** | Planner → specialist → Security → QA handoffs | `agent-kit session handoff` + IDE subagents — the kit's core operating model |
+| **Background / overnight loop** | Runs without a human present | **Defer by default** — requires worktree policy, cost caps, kill switches, and stronger eval gates than agent freedom |
+
+## Practical Rule
+
+Climb maturity by adding **checkpoints** (tests, audit, guards, human review), not by removing them. Unsupervised loops are only healthy when **eval gates are stronger than the agent's freedom**.
+
+## Eval-Driven PR Loop (recommended)
+
+For feature work in a kit-consuming project:
+
+1. **Plan** — Planner classifies scope; Lead Architect maps affected layers when the change is core.
+2. **Implement** — Next.js / Supabase engineers (or general agent with council rules loaded).
+3. **Check** — run the smallest reliable gate set:
+   ```bash
+   npm test
+   agent-kit audit --min-readiness baseline-setup
+   agent-kit adapter validate all   # when IDE surfaces change
+   ```
+4. **Fix** — repeat implement/check until green or blocked on a documented gap.
+5. **Record** — `agent-kit session render` and mirror summary in `COUNCIL.md` for meaningful multi-agent work.
+
+BaseRepo maintainers use the same pattern at repo scale:
+
+```bash
+npm run release:check    # tests, build, package validate, smokes, adapter validate
+npm run smoke:audit-gate
+```
+
+## Council Loop (multi-agent)
+
+The default handoff order lives in `AGENTS.md` and `.agent-kit/agent-roster.json`:
+
+1. Planner — scope, workflow, council selection
+2. Lead Architect — core changes
+3. Domain engineers — data, UI, copy as needed
+4. Security Reviewer — auth, mutations, secrets, dependencies, release risk
+5. QA Engineer — behavior evidence
+6. Documentation Maintainer — living docs and council record
+
+Use Agent Studio when the CLI is available:
+
+```bash
+agent-kit session start --workflow core-change --request "Short title"
+agent-kit session handoff --from planner --to lead-architect --decision "..." --risk "..." --next "..." --evidence "..."
+agent-kit session verify --command "npm test" --result pass
+agent-kit session output phased-checklist --status complete --evidence "..."
+agent-kit session render
+```
+
+When CLI tooling is unavailable, append the session template in `COUNCIL.md` (see `MAINTAINER_RELEASE.md` for kit release evidence).
+
+## Hooks And Local Automation (Level 6 enablers)
+
+The kit does **not** ship unsupervised orchestration. It documents safe local enablers:
+
+| Pattern | Purpose | Starting point |
+| --- | --- | --- |
+| Pre-commit test or audit | Catch drift before commit | `.agent-kit/prompts/audit-project-setup.md`, project `npm test` |
+| Post-edit lint/typecheck | Fast feedback on save | Project ESLint / `tsc --noEmit` in editor or CI |
+| PR CI audit gate | Block merge below readiness | `.github/workflows/agent-kit-audit.yml` template |
+| Adapter validate on PR | Prove IDE templates stay shippable | `agent-kit adapter validate all` (BaseRepo: `npm run adapter:validate` in `release:check`) |
+
+For Cursor-specific hook/automation patterns, see Cursor Automations docs and keep Planner-first triage **opt-in** — never as a replacement for Security Reviewer or human release approval.
+
+## MCP Routing (delegation hint)
+
+Match MCP servers to council roles in consuming projects:
+
+| Role | Typical MCP use |
+| --- | --- |
+| Supabase/Postgres Engineer | Schema, migrations, RLS, logs, advisors |
+| Security Reviewer | Dependency/advisory checks; no broad production writes without review |
+| Deployment/Observability Engineer | Hosting logs, release status, error tracking |
+| QA Engineer | Test runners, visual diff tools where configured |
+
+Record active MCP surfaces in `ASSISTANT_ADAPTERS.md` when they affect council behavior.
+
+## What Not To Default
+
+- Overnight unsupervised agent runs on auth, RLS, or release tooling
+- Agents managing agents without eval harness and kill switches
+- Removing human review from publish, migration, or security-sensitive paths
+- Duplicating runtime product agents inside the kit repo (wrong shape for agent-kit)
+
+## Related Docs
+
+- `AGENTS.md` — council roles and default handoffs
+- `QUALITY_GATES.md` — Baseline / Strong / Mature evidence tiers
+- `COUNCIL.md` — session evidence template
+- `MAINTAINER_RELEASE.md` — kit maintainer release session checklist
+- `research/summaries/agentic-engineering-maturity-levels.md` — L3–L8 ladder and office integration
+- `TESTING.md` — project test and CI gate expectations
+- `PUBLISH.md` — npm publish runbook

package/MAINTAINER_RELEASE.md

@@ -0,0 +1,100 @@
+# Maintainer Release Evidence
+
+Use this checklist when shipping `@appsforgood/next-supabase-kit` releases. It aligns kit maintainer practice with the **Strong** tier in `QUALITY_GATES.md`: council sessions record workflow, decision, risk, next handoff, required outputs, and evidence.
+
+For loop patterns and safe automation limits, see [LOOP_CODING.md](LOOP_CODING.md). For publish steps, see [PUBLISH.md](PUBLISH.md).
+
+## When To Open A Session
+
+Start `agent-kit session` (or a `COUNCIL.md` entry) when the release includes any of:
+
+- CLI or install behavior changes
+- New or changed IDE adapter surfaces (Cursor, Codex, Claude, Copilot, Antigravity)
+- Audit, roster, schema, or Agent Studio contract changes
+- Security-sensitive dependency or publish pipeline changes
+- Multi-agent work spanning Planner → Architect → QA
+
+Skip a formal session only for typo-only doc fixes with no behavioral impact.
+
+## Bootstrap Maintainer Dogfood
+
+Maintainers run the kit locally on BaseRepo without committing the overlay:
+
+```bash
+npm run dogfood:init
+node dist/index.js adapter validate cursor
+node dist/index.js adapter validate codex
+```
+
+Generated paths (`.agent-kit/`, `.cursor/`, `.codex/`, root council docs from init) are **gitignored**. Kit source stays in `templates/`, `assistant-adapters/`, and tracked root docs such as `DOCS.md` and `SPEC.md`.
+
+## Release Session Workflow
+
+```bash
+agent-kit session start --workflow release --request "Release vX.Y.Z"
+agent-kit session decision --agent planner --decision "..." --risk "..." --next "lead-architect" --evidence "..."
+agent-kit session verify --command "npm run release:check" --result pass --notes "..."
+agent-kit session verify --command "npm run smoke:audit-gate" --result pass
+agent-kit session output changelog --status complete --evidence "CHANGELOG.md#X.Y.Z"
+agent-kit session output test-evidence --status complete --evidence "vitest + smokes green"
+agent-kit session output publish-evidence --status complete --evidence "npm run publish:verify or GitHub Release vX.Y.Z"
+agent-kit session render
+```
+
+After publish, append a short evidence block to [DOGFOOD.md](DOGFOOD.md) (public-safe, no local paths).
+
+## COUNCIL.md Mirror Template
+
+When Agent Studio CLI is unavailable, paste this block into root `COUNCIL.md` (maintainer overlay, gitignored) or into the PR description:
+
+```md
+## YYYY-MM-DD - Release vX.Y.Z
+
+- Workflow: release
+- Status: complete
+- Request: Ship @appsforgood/next-supabase-kit@X.Y.Z
+- Affected layers: CLI, install, adapters, docs, CI, deployment
+
+### Required Outputs
+
+| Output | Status | Evidence |
+| --- | --- | --- |
+| Phased checklist | Complete | ROADMAP / PR scope |
+| Architecture decision | Complete/N/A | DECISIONS.md or PR note |
+| Security review | Complete | Dependency audit in release:check; no secret in adapters |
+| Test evidence | Complete | npm run release:check; npm run smoke:audit-gate |
+| Adapter validation | Complete | npm run adapter:validate (all IDE templates) |
+| Docs impact | Complete | CHANGELOG.md, DOCS.md, PUBLISH.md if process changed |
+| Publish verification | Complete | npm run publish:verify or Release workflow green |
+
+### Handoffs
+
+| Agent | Decision | Risk | Next Handoff | Evidence |
+| --- | --- | --- | --- | --- |
+| Planner | Release scope approved | Missed breaking change | Lead Architect / QA | PR + CHANGELOG |
+| QA Engineer | release:check green | Residual flake | Documentation Maintainer | CI logs |
+| Documentation Maintainer | CHANGELOG + DOGFOOD updated | Stale public evidence | Deployment/Observability | DOGFOOD.md entry |
+
+### Verification
+
+| Command Or Review | Result | Notes |
+| --- | --- | --- |
+| npm run release:check | Pass | Includes adapter:validate |
+| npm run smoke:audit-gate | Pass | baseline-setup, 0 failures |
+| npm run publish:verify | Pass/Skipped | Required after registry publish |
+```
+
+## Pre-Merge Gate (BaseRepo)
+
+Every release PR must pass:
+
+1. `npm run release:check` (tests, build, package validate, smokes, **adapter validate all**, audit, pack dry-run)
+2. `npm run smoke:audit-gate`
+3. CHANGELOG section for the target version
+4. Session render or COUNCIL mirror with verification table filled in
+
+## Post-Publish
+
+1. Run `npm run publish:verify` after registry propagation (or confirm Release workflow verification).
+2. Update `DOGFOOD.md` with publish verification snapshot (no machine paths).
+3. Mark release items in `ROADMAP.md`.

package/README.md

@@ -1,5 +1,11 @@
 # Agent Skills Next/Supabase Kit
 
+[![CI](https://github.com/lukey662/agentsandskills/actions/workflows/ci.yml/badge.svg)](https://github.com/lukey662/agentsandskills/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/%40appsforgood%2Fnext-supabase-kit)](https://www.npmjs.com/package/@appsforgood/next-supabase-kit)
+[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/lukey662/agentsandskills/badge)](https://scorecard.dev/viewer/?uri=github.com/lukey662/agentsandskills)
+[![CodeQL](https://github.com/lukey662/agentsandskills/actions/workflows/codeql.yml/badge.svg)](https://github.com/lukey662/agentsandskills/actions/workflows/codeql.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
 `@appsforgood/next-supabase-kit` installs an agent operating system for Next.js + Supabase projects.
 
 It gives agentic coders a default council roster, reusable skills, handoff rules, model-routing guidance, markdown docs, frontend design gates, Supabase/RLS security checks, upgrade workflows, and audit commands.
@@ -14,7 +20,7 @@ It also includes a local Agent Studio workflow: project context, durable human c
 
 ## Quick Start
 
-Use this in a Next.js + Supabase project after the public package is available on npm:
+Use this in a Next.js + Supabase project:
 
 ```bash
 npx @appsforgood/next-supabase-kit init --stack next-supabase --setup --open
@@ -33,6 +39,34 @@ npx @appsforgood/next-supabase-kit adapter validate antigravity
 
 The installer preserves existing docs. If a file already exists and differs from the template, the new version is written to `.agent-kit/conflicts/` for review.
 
+### See It In Action
+
+```text
+$ agent-kit init --stack next-supabase
+agent-kit installed (stack: next-supabase)
+Created (21)
+  AGENTS.md
+  AGENT_ROSTER.md
+  ASSISTANT_ADAPTERS.md
+  ...
+  .cursor/rules/cursor-agent-kit.mdc
+  .agent-kit/agent-roster.json
+  .agent-kit/model-routing.json
+
+Manifest: .agent-kit/manifest.json
+Next: run agent-kit audit to check readiness.
+
+$ agent-kit audit
+READINESS baseline-setup: Agent kit setup is valid, but project-specific
+evidence still needs to replace starter placeholders.
+SUMMARY pass=60 warn=3 fail=0
+NEXT ACTIONS
+- Run agent-kit onboard or agent-kit init --guided so agents can start
+  with project-specific context.
+```
+
+Every command accepts `--json` for machine-readable output, and mutating commands (`init`, `update`, `add skill`) accept `--dry-run`. A `vhs` tape for regenerating the animated demo lives at `docs/demo.tape`.
+
 For local development of this repo:
 
 ```bash
@@ -63,7 +97,7 @@ Default routing:
 - Planner handles plans, roadmaps, scope, and ambiguous requests first.
 - Lead Architect reviews core changes before implementation.
 - Security Reviewer joins auth, RLS, data mutation, dependency, secret, external-call, and release-risk work.
-- Frontend Design Lead owns content-first design, reference-led critique, distinctiveness benchmarking, product-quality scoring, and visual QA.
+- Frontend Design Lead owns content-first design, reference-led critique, distinctiveness benchmarking, product-quality scoring, UI detector severity review, command-based polish/audit loops, and visual QA.
 - Marketing Copy Lead owns public-facing and conversion-facing copy, positioning, proof, objections, voice, and CTA hierarchy.
 - QA Engineer verifies behavior changes before completion.
 - Documentation Maintainer keeps the living markdown current.
@@ -160,7 +194,7 @@ Agent Kit separates the mechanisms that make AI coding repeatable:
 - Instructions: `AGENTS.md`, assistant adapters, and IDE-specific rule files.
 - Roster: `.agent-kit/agent-roster.json` chooses agents, workflows, and handoffs.
 - Skills: `.agent-kit/skills/` keeps specialist workflows reusable.
-- Runtime commands: Antigravity `commands/*.toml` expose `/setup`, `/audit`, `/plan`, `/handoff`, `/frontend`, `/security`, `/copy`, `/ship`, and `/upgrade` as native adapter entrypoints.
+- Runtime commands: Antigravity `commands/*.toml` expose `/setup`, `/audit`, `/plan`, `/handoff`, `/frontend`, focused UI improvement commands, `/security`, `/copy`, `/ship`, and `/upgrade` as native adapter entrypoints.
 - Portable skills: `runtime-skills/*/SKILL.md` wraps canonical `skills/*.md` files for runtimes that discover skill directories.
 - Model routing: `MODEL_ROUTING.md` and `.agent-kit/model-routing.json` map agents to model profiles.
 - Messaging: `MESSAGING.md` records audience, pain, outcome, proof, objections, voice, and conversion evidence for public-facing copy.
@@ -189,6 +223,8 @@ Significant UI work should prove:
 
 The Frontend Design Lead should reject work that would still look valid for another product after only changing the logo or headline.
 
+Operational UI improvement workflows live in `.agent-kit/prompts/ui-command-index.md` and ship as Antigravity commands: `/ui-audit`, `/ui-polish`, `/layout-cleanup`, `/responsive-cleanup`, `/accessibility-pass`, `/distinctiveness-pass`, `/screenshot-critique`, and `/browser-qa`. Use `.agent-kit/checklists/ui-detectors.md` for deterministic blocker/major/minor findings and `.agent-kit/checklists/ui-acceptance-rubric.md` for pass/fail decisions. High-risk UI work requires desktop and mobile screenshots plus authenticated or permission-state evidence when the surface is not public.
+
 ## Security Bar
 
 The kit treats these as defaults, not optional polish:
@@ -255,7 +291,7 @@ Release expectations:
 - Dependency Review, CodeQL, OpenSSF Scorecard, Dependabot, SBOM validation, and SBOM attestation.
 - Post-publish verification with `npm run publish:verify`.
 
-Public release remains gated until the npm scope/package exists, Trusted Publishing is configured, and post-publish `npx` verification succeeds.
+The package is published to public npm under `@appsforgood/next-supabase-kit`. Every release must pass `npm run release:check` before publish and `npm run publish:verify` after (registry visibility, clean `npx` doctor/init/audit). Post-publish verification was last run 2026-07-02 against the live registry: doctor, init, and `audit --min-readiness baseline-setup` all passed with zero failures.
 
 ## Repository Health
 

package/REPOSITORY_SETTINGS.md

@@ -31,9 +31,9 @@ Create environment `npm-publish` with:
 - Required reviewers enabled.
 - Prevent self-review enabled where available.
 - Deployment branches restricted to `main` and release events.
-- No npm publish token secret for the trusted-publishing flow.
-- Any legacy npm token secrets deleted after Trusted Publishing is confirmed.
-- Optional fallback: a maintainer npm publish token secret on the `npm-publish` environment when trusted publishing returns 404 on PUT.
+- Preferred path: no npm publish token secret once Trusted Publishing is confirmed for this package.
+- Current fallback: a maintainer npm publish token secret on the release workflow so manual publish dispatch can complete until npm Trusted Publishing is configured.
+- Any fallback npm token secrets deleted after Trusted Publishing is confirmed.
 
 The npm trusted publisher must match:
 
@@ -66,6 +66,10 @@ Create labels from `.github/labels.yml`. Required label families:
 - Status: `needs-triage`, `blocked`, `good first issue`, `help wanted`
 - Risk: `risk: security`, `risk: breaking-change`
 
+## GitHub Pages
+
+Enable GitHub Pages with source "Deploy from a branch", branch `main`, folder `/docs`. The minimal docs site lives at `docs/index.md` with the `jekyll-theme-minimal` theme configured in `docs/_config.yml`. Update `docs/index.md` when the CLI surface, readiness levels, or quick-start commands change.
+
 ## Review Cadence
 
 Review these settings before every public release and after any workflow, release, permission, package, or security-policy change.

package/SUPPLY_CHAIN.md

@@ -5,12 +5,12 @@ This package is intended for public npm distribution and downstream project boot
 ## Publish Identity
 
 - Public package: `@appsforgood/next-supabase-kit`.
-- Publish path: GitHub Actions release workflow through npm Trusted Publishing.
-- Authentication: OIDC trusted publisher, not a long-lived npm automation token.
+- Publish path: GitHub Actions release workflow through npm Trusted Publishing when configured, with a token-backed publish fallback for the current npm package setup.
+- Authentication: prefer OIDC trusted publisher; the fallback uses a scoped npm automation token stored as a GitHub Actions secret.
 - Environment: `npm-publish`.
 - Trusted publisher must be scoped to repository `lukey662/agentsandskills`, workflow `release.yml`, and allowed action `npm publish`.
 
-When npm Trusted Publishing is used from a public GitHub repository for a public package, npm generates provenance attestations automatically. The release workflow keeps `id-token: write` for this reason and does not set `NODE_AUTH_TOKEN` for publishing.
+When npm Trusted Publishing is used from a public GitHub repository for a public package, npm generates provenance attestations automatically. Until that package-level publisher is confirmed in npm, the release workflow publishes with the configured secret and `--provenance` so npm still receives GitHub Actions provenance.
 
 The release workflow also creates a deterministic package tarball, generates a CycloneDX SBOM from `package-lock.json`, uploads the tarball, SBOM, and pack metadata as release evidence, and attests the SBOM against the exact tarball path that is published to npm.
 
@@ -47,9 +47,9 @@ The release workflow and `npm run publish:verify` both use `scripts/post-publish
 
 ## Maintainer Rules
 
-- Do not use bypass-2FA npm publish tokens for automation.
+- Do not use bypass-2FA npm publish tokens for automation; any fallback token must be scoped for package publishing and stored only as a GitHub Actions secret.
 - Do not publish from unreviewed branches or untrusted workflow changes.
 - Treat workflow edits as release-risk changes requiring security and maintainer review.
-- Rotate and delete legacy publish secrets after Trusted Publishing is confirmed.
+- Rotate and delete fallback publish secrets after Trusted Publishing is confirmed.
 - Keep package contents free of secrets, private downstream data, and copied third-party source.
 - Keep SBOM generation and attestation in the shared release path; do not publish an unattested tarball when the workflow is available.

package/UPGRADE.md

@@ -78,4 +78,5 @@ Keep rollback evidence next to the upgrade:
 | Date | From | To | Scope | Evidence | Owner |
 | --- | --- | --- | --- | --- | --- |
 | 2026-06-14 | TypeScript 5 / Node 22 types | TypeScript 6 / Node 25 types | Dev dependency update for package validation and CI parity | `npm run typecheck`, `npm test`, `npm audit --audit-level=moderate` | Maintainers |
-| TBD | TBD | TBD | TBD | TBD | TBD |
+| 2026-06 | 0.1.0 | 0.1.1 | Package rename to `@appsforgood/next-supabase-kit`, harness readiness gates, adapter install on init, publish prep | `CHANGELOG.md` 0.1.1 entry, `npm run release:check` green, commit `37e1a0f` | lukey662 |
+| 2026-07-02 | none | 0.1.1 (self-install) | Dogfooded the kit into this repo's own root: `agent-kit init` installed root docs, `.agent-kit/`, and confirmed the Cursor rules' referenced files exist | `.agent-kit/manifest.json`, `agent-kit audit` zero failures, `COUNCIL.md` 2026-07-02 session | lukey662 |

package/antigravity/commands/accessibility-pass.toml

@@ -0,0 +1,16 @@
+name = "accessibility-pass"
+description = "Run a WCAG 2.1 AA-oriented UI pass for semantics, keyboard flow, focus, labels, contrast, and motion."
+
+prompt = """
+Run the accessibility pass workflow.
+
+Canonical sources: DESIGN.md, STYLE_GUIDE.md, TESTING.md, QUALITY_GATES.md, .agent-kit/agent-roster.json, .agent-kit/skills/ui-improvement-harness.md, .agent-kit/skills/accessibility-wcag.md, .agent-kit/checklists/ui-detectors.md, .agent-kit/checklists/ui-acceptance-rubric.md, and .agent-kit/prompts/ui-command-index.md.
+
+Workflow:
+1. Check semantics, headings, landmarks, forms, labels, tables, buttons, and ARIA use.
+2. Check keyboard navigation, visible focus, tab order, escape/close behavior, and skip path when applicable.
+3. Check contrast, reduced motion, error association, touch targets, and status announcements.
+4. Keep accessibility checks separate from visual-only approval.
+
+Required outputs: accessibility findings by severity, fixes made or proposed, skipped checks, test evidence, remaining risks.
+"""

package/antigravity/commands/browser-qa.toml

@@ -0,0 +1,18 @@
+name = "browser-qa"
+description = "Run a live browser QA loop with desktop, mobile, state, and authenticated screen evidence."
+
+prompt = """
+Run the live browser QA workflow.
+
+Canonical sources: DESIGN.md, STYLE_GUIDE.md, TESTING.md, QUALITY_GATES.md, .agent-kit/agent-roster.json, .agent-kit/skills/ui-improvement-harness.md, .agent-kit/checklists/ui-detectors.md, .agent-kit/checklists/ui-acceptance-rubric.md, .agent-kit/prompts/screenshot-review.md, .agent-kit/prompts/visual-qa-plan.md, and .agent-kit/prompts/ui-command-index.md.
+
+Workflow:
+1. Start or identify the dev/preview server and target routes.
+2. Open the target with required auth, role, tenant, and data state.
+3. Capture desktop and mobile screenshots.
+4. Run detector, screenshot critique, accessibility pass, and responsive cleanup.
+5. Apply scoped fixes and repeat until no blockers remain and major findings are fixed or documented.
+6. Record evidence with agent-kit session output when Agent Studio is in use.
+
+Required outputs: route, auth state, commands run, screenshots, detector results, fixes, final verdict.
+"""

package/antigravity/commands/distinctiveness-pass.toml

@@ -0,0 +1,16 @@
+name = "distinctiveness-pass"
+description = "Check that UI is product-specific, source-safe, and not generic SaaS or AI-site styling."
+
+prompt = """
+Run the visual distinctiveness pass workflow.
+
+Canonical sources: DESIGN.md, STYLE_GUIDE.md, MESSAGING.md, QUALITY_GATES.md, .agent-kit/agent-roster.json, .agent-kit/skills/ui-improvement-harness.md, .agent-kit/skills/frontend-distinctiveness-benchmark.md, .agent-kit/checklists/ui-detectors.md, .agent-kit/checklists/ui-acceptance-rubric.md, and .agent-kit/prompts/ui-command-index.md.
+
+Workflow:
+1. Compare the first viewport to product category, audience, workflow, and content fingerprint.
+2. Confirm references were translated into lessons without copying source layouts, copy, assets, or brand marks.
+3. Identify fake metrics, vague claims, abstract filler, interchangeable card stacks, and generic visual tropes.
+4. Re-score distinctiveness and product quality where significant UI work is involved.
+
+Required outputs: product-specific evidence, generic-risk findings, source-safety notes, required changes, final distinctiveness verdict.
+"""

package/antigravity/commands/frontend.toml

@@ -4,14 +4,15 @@ description = "Route frontend work through content-first design, accessibility,
 prompt = """
 Run the frontend-change workflow.
 
-Canonical sources: DESIGN.md, STYLE_GUIDE.md, MESSAGING.md, QUALITY_GATES.md, .agent-kit/agent-roster.json, .agent-kit/design-briefs/, .agent-kit/prompts/screenshot-review.md, and .agent-kit/skills/frontend-design-system.md.
+Canonical sources: DESIGN.md, STYLE_GUIDE.md, MESSAGING.md, QUALITY_GATES.md, .agent-kit/agent-roster.json, .agent-kit/design-briefs/, .agent-kit/prompts/screenshot-review.md, .agent-kit/prompts/ui-command-index.md, .agent-kit/checklists/ui-detectors.md, .agent-kit/checklists/ui-acceptance-rubric.md, .agent-kit/skills/frontend-design-system.md, and .agent-kit/skills/ui-improvement-harness.md.
 
 Workflow:
 1. Start with Frontend Design Lead before implementation.
 2. Confirm brand/content intake, user needs, real content, creative direction, references, anti-references, and source-safety notes.
 3. Require distinctiveness benchmark and product-quality scorecard for significant UI.
-4. Preserve WCAG 2.1 AA, keyboard flow, responsive states, and loading/error/empty/success states.
-5. Record visual QA and accessibility evidence with `agent-kit session output`.
+4. Apply the UI improvement command index when auditing, polishing, cleaning layout, reviewing screenshots, or running browser QA.
+5. Preserve WCAG 2.1 AA, keyboard flow, responsive states, and loading/error/empty/success states.
+6. Record UI detector findings, visual QA, and accessibility evidence with `agent-kit session output`.
 
-Required outputs: design direction, reference evidence, product-specific UI rationale, state coverage, accessibility checks, desktop/mobile visual QA.
+Required outputs: design direction, reference evidence, product-specific UI rationale, UI detector findings, state coverage, accessibility checks, desktop/mobile visual QA, authenticated screen evidence when applicable.
 """

package/antigravity/commands/layout-cleanup.toml

@@ -0,0 +1,16 @@
+name = "layout-cleanup"
+description = "Clean crowded layouts, weak hierarchy, card nesting, overflow, and inconsistent spacing."
+
+prompt = """
+Run the layout cleanup workflow.
+
+Canonical sources: DESIGN.md, STYLE_GUIDE.md, TESTING.md, QUALITY_GATES.md, .agent-kit/agent-roster.json, .agent-kit/skills/ui-improvement-harness.md, .agent-kit/checklists/ui-detectors.md, .agent-kit/checklists/ui-acceptance-rubric.md, and .agent-kit/prompts/ui-command-index.md.
+
+Workflow:
+1. Identify primary task, secondary tasks, content hierarchy, and target viewport range.
+2. Remove unnecessary nesting, repeated surfaces, card-within-card patterns, arbitrary dividers, and workflow-obscuring decoration.
+3. Normalize spacing, grouping, alignment, heading scale, and responsive containers.
+4. Verify text fit, truncation, overlap, and horizontal overflow on desktop and mobile.
+
+Required outputs: layout findings, cleanup actions, preserved workflow, desktop/mobile evidence, remaining layout risks.
+"""

package/antigravity/commands/responsive-cleanup.toml

@@ -0,0 +1,16 @@
+name = "responsive-cleanup"
+description = "Verify and repair mobile and responsive UI behavior with required desktop and mobile evidence."
+
+prompt = """
+Run the responsive cleanup workflow.
+
+Canonical sources: DESIGN.md, STYLE_GUIDE.md, TESTING.md, QUALITY_GATES.md, .agent-kit/agent-roster.json, .agent-kit/skills/ui-improvement-harness.md, .agent-kit/checklists/ui-detectors.md, .agent-kit/checklists/ui-acceptance-rubric.md, and .agent-kit/prompts/ui-command-index.md.
+
+Workflow:
+1. Review mobile width, desktop width, and project-specific breakpoint assumptions.
+2. Verify tap targets, text fit, navigation, primary action visibility, sticky UI, scroll behavior, and viewport-safe spacing.
+3. Verify relevant loading, empty, error, disabled, success, permission, and focus states on mobile.
+4. Capture or request desktop and mobile screenshots before acceptance.
+
+Required outputs: viewports checked, responsive findings, fixes made or proposed, screenshots, remaining risks.
+"""

package/antigravity/commands/screenshot-critique.toml

@@ -0,0 +1,16 @@
+name = "screenshot-critique"
+description = "Critique desktop, mobile, state, and authenticated screenshots against design and detector rules."
+
+prompt = """
+Run the screenshot critique workflow.
+
+Canonical sources: DESIGN.md, STYLE_GUIDE.md, TESTING.md, QUALITY_GATES.md, .agent-kit/agent-roster.json, .agent-kit/skills/ui-improvement-harness.md, .agent-kit/checklists/ui-detectors.md, .agent-kit/checklists/ui-acceptance-rubric.md, .agent-kit/prompts/screenshot-review.md, and .agent-kit/prompts/ui-command-index.md.
+
+Workflow:
+1. Name each screenshot, viewport, route, auth state, data state, and UI state.
+2. Run screenshot review, detector checklist, and accessibility risk scan.
+3. Compare against DESIGN.md, STYLE_GUIDE.md, and selected creative direction.
+4. Return concrete fixes and missing screenshot evidence.
+
+Required outputs: screenshot inventory, blockers, high-value fixes, accepted areas, missing screenshots, release verdict.
+"""

package/antigravity/commands/ui-audit.toml

@@ -0,0 +1,17 @@
+name = "ui-audit"
+description = "Run a deterministic UI audit with severity-based detector findings and release evidence."
+
+prompt = """
+Run the UI audit workflow.
+
+Canonical sources: DESIGN.md, STYLE_GUIDE.md, TESTING.md, QUALITY_GATES.md, .agent-kit/agent-roster.json, .agent-kit/skills/ui-improvement-harness.md, .agent-kit/checklists/ui-detectors.md, .agent-kit/checklists/ui-acceptance-rubric.md, and .agent-kit/prompts/ui-command-index.md.
+
+Workflow:
+1. Identify target route, component, workflow, auth state, data state, and risk tier.
+2. Load product/design context and relevant design brief.
+3. Review desktop and mobile evidence, or state which evidence must still be captured.
+4. Run the UI detector checklist and classify blockers, majors, minors, passes, and not-applicable items.
+5. Return required fixes, accepted exceptions, preserved capabilities, and pass/fail verdict.
+
+Required outputs: target surface, risk tier, detector findings by severity, missing evidence, release verdict.
+"""

package/antigravity/commands/ui-polish.toml

@@ -0,0 +1,17 @@
+name = "ui-polish"
+description = "Improve UI hierarchy, spacing, state feedback, and visual finish through detector-guided polish."
+
+prompt = """
+Run the UI polish workflow.
+
+Canonical sources: DESIGN.md, STYLE_GUIDE.md, TESTING.md, QUALITY_GATES.md, .agent-kit/agent-roster.json, .agent-kit/skills/ui-improvement-harness.md, .agent-kit/checklists/ui-detectors.md, .agent-kit/checklists/ui-acceptance-rubric.md, and .agent-kit/prompts/ui-command-index.md.
+
+Workflow:
+1. Start from detector findings, screenshots, or a named target surface.
+2. Preserve product behavior, auth boundaries, copy claims, data contracts, and existing component patterns.
+3. Improve hierarchy, spacing, density, alignment, component states, and interaction feedback.
+4. Remove decorative clutter and generic SaaS or AI-site defaults.
+5. Re-run detector and screenshot critique after the scoped polish pass.
+
+Required outputs: polish goals, changes made or proposed, detector deltas, screenshot evidence, residual risks.
+"""

package/antigravity/plugin.json

@@ -21,6 +21,14 @@
     { "name": "plan", "path": "commands/plan.toml" },
     { "name": "handoff", "path": "commands/handoff.toml" },
     { "name": "frontend", "path": "commands/frontend.toml" },
+    { "name": "ui-audit", "path": "commands/ui-audit.toml" },
+    { "name": "ui-polish", "path": "commands/ui-polish.toml" },
+    { "name": "layout-cleanup", "path": "commands/layout-cleanup.toml" },
+    { "name": "responsive-cleanup", "path": "commands/responsive-cleanup.toml" },
+    { "name": "accessibility-pass", "path": "commands/accessibility-pass.toml" },
+    { "name": "distinctiveness-pass", "path": "commands/distinctiveness-pass.toml" },
+    { "name": "screenshot-critique", "path": "commands/screenshot-critique.toml" },
+    { "name": "browser-qa", "path": "commands/browser-qa.toml" },
     { "name": "security", "path": "commands/security.toml" },
     { "name": "copy", "path": "commands/copy.toml" },
     { "name": "ship", "path": "commands/ship.toml" },
@@ -38,6 +46,7 @@
     { "name": "frontend-distinctiveness-benchmark", "path": "../runtime-skills/frontend-distinctiveness-benchmark/SKILL.md" },
     { "name": "frontend-product-quality-rubric", "path": "../runtime-skills/frontend-product-quality-rubric/SKILL.md" },
     { "name": "landing-page-copy", "path": "../runtime-skills/landing-page-copy/SKILL.md" },
+    { "name": "ui-improvement-harness", "path": "../runtime-skills/ui-improvement-harness/SKILL.md" },
     { "name": "nextjs-app-router", "path": "../runtime-skills/nextjs-app-router/SKILL.md" },
     { "name": "onboarding-empty-state-copy", "path": "../runtime-skills/onboarding-empty-state-copy/SKILL.md" },
     { "name": "owasp-security-review", "path": "../runtime-skills/owasp-security-review/SKILL.md" },