@appsforgood/next-supabase-kit 0.2.0 → 0.3.0

package/README.md

@@ -1,4 +1,4 @@
-# Agent Skills Next/Supabase Kit
+# Agent Kit for Next.js + Supabase
 
 [![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)
@@ -6,494 +6,568 @@
 [![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.
+`@appsforgood/next-supabase-kit` installs versioned agent instructions, specialist roles, reusable skills, project documentation, security checks, UI review gates, and audit tooling into an existing repository.
 
-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.
+It is designed for teams using AI coding tools on Next.js and Supabase projects that need the work to remain reviewable, secure, and maintainable.
 
-The package answers one practical question:
+## Start Here
 
-> Does this project have the setup needed for secure, maintainable, non-generic Next.js + Supabase delivery?
+- [Quick start](#quick-start)
+- [First-run examples](#first-run-examples)
+- [Audit examples](#audit-examples)
+- [Common delivery workflows](#common-delivery-workflows)
+- [Updating an existing install](#updating-an-existing-install)
+- [Optional executable runtime](#optional-executable-runtime)
+- [Installed project contract](#installed-project-contract)
+- [Maintainer verification](#maintainer-verification)
 
-This is not just a prompt bundle. A project gets machine-readable agent routing, model profile routing, schema-backed council evidence, living documentation templates, research-backed quality gates, and CLI checks for drift.
+## What You Get
 
-It also includes a local Agent Studio workflow: project context, durable human corrections, append-only session events, and rendered Markdown transcripts that work without a database, web server, background daemon, or separate model API key.
+- A machine-readable council roster with explicit ownership and handoffs.
+- Instructions and adapters for Codex, Cursor, Claude Code, GitHub Copilot, and Antigravity.
+- Living `SPEC.md`, `DECISIONS.md`, `DESIGN.md`, `MESSAGING.md`, `SECURITY.md`, `TESTING.md`, and deployment documentation.
+- Supabase Auth, RLS, migration, service-role, and OWASP review rules.
+- Frontend design gates that reject generic gradients, card soup, fake metrics, vague SaaS copy, inaccessible state styling, and other common AI-generated UI patterns.
+- Local project context, durable human corrections, council-session evidence, and static or live Agent Studio views.
+- A CLI that detects missing setup, stale templates, unsupported claims, weak evidence, and release-readiness gaps.
+- An optional runtime for checkpointed LangGraph execution with provider adapters, MCP policy, approvals, Docker isolation, and Git worktrees.
 
-Projects that need executable council workflows can add the optional `@appsforgood/agent-kit-runtime` package. It compiles the same roster into checkpointed LangGraph runs with provider/MCP adapters, risk approvals, Docker-first mutation isolation, Git worktrees, and redacted evidence.
+## Choose A Mode
+
+| Mode | Package | What runs |
+| --- | --- | --- |
+| Instructions and audits | `@appsforgood/next-supabase-kit` | Your coding assistant follows installed files; the CLI installs, validates, records, and audits evidence |
+| Executable council | Add `@appsforgood/agent-kit-runtime` | The CLI compiles the roster into checkpointed workflows with approval gates and isolated worktrees |
+
+The base kit does not call a model provider. Installing instructions does not prove that an executable council ran. Only `agent-kit orchestrate ...` produces runtime checkpoints and run evidence.
+
+## Requirements
+
+- Node.js 20 or newer.
+- Git for update, session, and worktree-aware workflows.
+- A Next.js + Supabase project is the primary profile, but the documentation and audit model can be adapted to adjacent stacks.
+- Docker is required only for mutation commands in the optional executable runtime.
 
 ## Quick Start
 
-Use the current stable package in a Next.js + Supabase project:
+### Zero-install trial
+
+Run the current package directly in the repository you want to prepare:
 
 ```bash
-npx @appsforgood/next-supabase-kit@latest init --stack next-supabase --setup --open
-npx @appsforgood/next-supabase-kit audit
-npx @appsforgood/next-supabase-kit audit --min-readiness baseline-setup
+npx --yes @appsforgood/next-supabase-kit@latest init --stack next-supabase --setup --open
+npx --yes @appsforgood/next-supabase-kit@latest audit
+npx --yes @appsforgood/next-supabase-kit@latest audit --min-readiness baseline-setup
 ```
 
-After install, the **Agent Office** setup view teaches agents about your project (~10 min). Resume anytime:
+The first command installs project-owned documentation and `.agent-kit/` assets, then opens the local Agent Office setup flow. Existing customized files are preserved; changed templates are written to `.agent-kit/conflicts/` for review.
+
+### Local development dependency
+
+Install the CLI when the project will use it repeatedly or in CI:
 
 ```bash
-npx @appsforgood/next-supabase-kit setup --open
-npx @appsforgood/next-supabase-kit setup --status
+npm install --save-dev @appsforgood/next-supabase-kit
+npx agent-kit init --stack next-supabase --setup --open
+npx agent-kit audit --min-readiness baseline-setup
 ```
 
-Promote IDE/runtime adapters after install:
+Add convenient package scripts:
 
-```bash
-npx @appsforgood/next-supabase-kit init --activate cursor --activate antigravity
-npx @appsforgood/next-supabase-kit adapter validate all
+```json
+{
+  "scripts": {
+    "agent:audit": "agent-kit audit --min-readiness baseline-setup",
+    "agent:setup": "agent-kit setup --open",
+    "agent:studio": "agent-kit studio serve --open"
+  }
+}
 ```
 
-Optional executable orchestration:
+Then run:
 
 ```bash
-npm install --save-dev @appsforgood/agent-kit-runtime
-agent-kit orchestrate validate
-agent-kit orchestrate plan "Describe the goal"
+npm run agent:audit
 ```
 
-`.agent-kit/orchestrator.json` is installed disabled. Configure verified provider model IDs and `env:` or `keychain:` credential references before enabling it.
+## First-Run Examples
+
+### Preview before writing
 
-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.
+```bash
+npx agent-kit init --stack next-supabase --guided --dry-run --json
+```
 
-### See It In Action
+### Install without opening a browser
 
-```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
+```bash
+npx agent-kit init --stack next-supabase --no-setup
+npx agent-kit context init
+npx agent-kit context ask
+```
 
-Manifest: .agent-kit/manifest.json
-Next: run agent-kit audit to check readiness.
+GitHub Actions is off by default. Opt in to the advisory audit workflow only when the repository has working Actions entitlement:
 
-$ 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.
+```bash
+npx agent-kit init --github-actions
 ```
 
-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`.
+The workflow runs manually by default. Set the repository variable `AGENT_KIT_ACTIONS_ENABLED=true` to enable its push and pull-request jobs. Do not make the check required until the repository can reliably start Actions jobs.
 
-For local development of this repo:
+### Resume project onboarding
 
 ```bash
-npm install
-npm run build
-npm test
-npm run release:check
+npx agent-kit setup --open
+npx agent-kit setup --status
 ```
 
-`npm run release:check` is the main pre-release proof command. It typechecks, tests, builds, install-smokes the package, checks examples, runs dependency audit, validates SBOM generation, and dry-runs packaging.
+The setup server binds to `127.0.0.1:9321` by default:
 
-## Workflow Commands
+- `/` or `/office`: Agent Office.
+- `/wizard`: form-based fallback.
 
-Twenty slash commands map to the delivery lifecycle. Each one activates the right council agents and skills automatically. Use them in Antigravity after `init --activate antigravity`, or as prompt prefixes in any IDE. Canonical workflow steps live in `.agent-kit/prompts/lifecycle-command-index.md` (delivery) and `.agent-kit/prompts/ui-command-index.md` (UI polish).
+Use a different port when needed:
 
-```text
-SETUP → SPEC/PLAN → BUILD → VERIFY → REVIEW → SHIP
+```bash
+npx agent-kit setup --port 9400 --open
 ```
 
-**Workflow commands** (`/setup`, `/spec`, …) are instruction adapters. **Package CLI** commands (`agent-kit init`, `audit`, `session`, `orchestrate`, …) are documented under [CLI Reference](#cli-reference) below. Cursor loads rules and skills from `init`; Antigravity gets native slash commands from `init --activate antigravity`. Only `agent-kit orchestrate` is evidence that the executable checkpointed council ran. See `ASSISTANT_ADAPTERS.md` for per-IDE setup.
-
-### Core lifecycle commands
+### Activate IDE adapters
 
-| What you're doing | Command | Key principle | Skills / council |
-| --- | --- | --- | --- |
-| Onboard project context | `/setup` | Context before code | Agent Office, project-context |
-| Define what to build | `/spec` | Spec before code | Planner, docs-maintainer |
-| Plan how to build it | `/plan` | Council before implementation | planning-council, lead-architect |
-| Route between agents | `/handoff` | Explicit handoffs | agent-handoff-tracing |
-| Build frontend/UI | `/frontend` | Content-first design | frontend-design-lead skills |
-| Check kit readiness | `/audit` | Evidence before claims | best-practice-maturity-review |
-| Prove behavior | `/test` | Tests are proof | testing-qa, qa-engineer |
-| Review before merge | `/review` | Improve code health | qa-engineer + security-reviewer |
-| Security signoff | `/security` | RLS at the boundary | owasp-security-review, supabase-auth-rls |
-| Public copy | `/copy` | Proof before publish | marketing-copy-lead |
-| Ship release | `/ship` | Faster is safer | deployment-observability, release gates |
-| Upgrade kit/deps | `/upgrade` | Diff before overwrite | upgrade-maintenance |
+```bash
+npx agent-kit init --activate cursor
+npx agent-kit init --activate codex
+npx agent-kit init --activate antigravity
+npx agent-kit adapter validate all
+```
 
-### UI harness commands
+Activation promotes the relevant adapter files. The IDE or coding agent still decides when and how to load them; review `ASSISTANT_ADAPTERS.md` for the exact behavior of each tool.
 
-Focused UI improvement commands. Full steps: `.agent-kit/prompts/ui-command-index.md`.
+## Audit Examples
 
-| What you're doing | Command | Key principle |
-| --- | --- | --- |
-| Audit UI before release | `/ui-audit` | Detect before ship |
-| Improve visual quality | `/ui-polish` | Scope-safe polish |
-| Repair layout structure | `/layout-cleanup` | Hierarchy over decoration |
-| Fix responsive behavior | `/responsive-cleanup` | Mobile is not an afterthought |
-| WCAG 2.1 AA pass | `/accessibility-pass` | Keyboard and contrast matter |
-| Prove product distinctiveness | `/distinctiveness-pass` | Not interchangeable SaaS |
-| Critique screenshots | `/screenshot-critique` | Evidence over opinion |
-| Live browser QA loop | `/browser-qa` | Measure in the real UI |
+### Human-readable readiness report
 
-Skills activate from task keywords and roster `defaultFor` tags—for example, schema/RLS work routes to **Supabase/Postgres Engineer** with `supabase-auth-rls` and `postgres-migrations`; App Router work routes to **Next.js Engineer** with `nextjs-app-router`. See `SKILLS.md` and `.agent-kit/agent-roster.json`.
+```bash
+npx agent-kit audit
+```
 
-### Council
+### Stable JSON output
 
-| Agent | Owns | Key skills |
-| --- | --- | --- |
-| Planner | Scope, roadmap, ambiguous requests | planning-council, agent-handoff-tracing |
-| Lead Architect | Core and cross-layer changes | nextjs-app-router, supabase-auth-rls, owasp-security-review |
-| Supabase/Postgres Engineer | Schema, migrations, RLS, auth | supabase-auth-rls, postgres-migrations |
-| Next.js Engineer | App Router, Server Actions, UI state | nextjs-app-router, frontend-design-system |
-| Frontend Design Lead | Design gates, visual QA, anti-generic UI | content-first-design, ui-improvement-harness |
-| Marketing Copy Lead | Positioning, conversion copy, CTAs | positioning-messaging, conversion-copywriting |
-| Security Reviewer | OWASP, auth boundaries, secrets | owasp-security-review, supabase-auth-rls |
-| QA Engineer | Tests, regression, acceptance evidence | testing-qa, visual-regression-qa |
-| Documentation Maintainer | Living docs, spec, decisions | docs-maintainer, planning-council |
-| Deployment/Observability Engineer | Release, rollback, monitoring | deployment-observability |
+```bash
+npx agent-kit audit --json
+npx agent-kit audit --schema-version 2 --format json
+```
 
-### Skills by lifecycle phase
+### SARIF for code-scanning systems
 
-Full skill list: `SKILLS.md`.
+```bash
+npx agent-kit audit --schema-version 2 --format sarif > agent-kit.sarif
+```
 
-**Define:** planning-council, agent-handoff-tracing, best-practice-maturity-review, docs-maintainer
+### Fail a local or explicitly enabled CI gate below the required evidence level
 
-**Build:** nextjs-app-router, supabase-auth-rls, postgres-migrations, content-first-design, frontend-design-system, ui-improvement-harness, positioning-messaging
+```bash
+npx agent-kit audit --min-readiness baseline-setup
+```
 
-**Verify:** testing-qa, visual-regression-qa, owasp-security-review, accessibility-wcag, reference-led-design-critique, frontend-product-quality-rubric
+Readiness levels are:
+
+1. `needs-setup`
+2. `baseline-setup`
+3. `needs-improvement`
+4. `best-practice-candidate`
+
+Example GitHub Actions job:
+
+```yaml
+name: Agent Kit Audit
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  audit:
+    if: ${{ github.event_name == 'workflow_dispatch' || vars.AGENT_KIT_ACTIONS_ENABLED == 'true' }}
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+        with:
+          persist-credentials: false
+      - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6
+        with:
+          node-version: 24
+      - run: npx --yes @appsforgood/next-supabase-kit@0.3.0 audit --min-readiness baseline-setup
+```
 
-**Ship:** deployment-observability, upgrade-maintenance
+Run `agent-kit init --github-actions` to install the maintained `.github/workflows/agent-kit-audit.yml` template. Fresh installs do not create an active hosted workflow. Account billing, spending-limit, or Actions-startup failures are external infrastructure failures; they do not replace required local test and audit evidence and do not block commit/push or normal phase progression. A project may separately make hosted checks required only after verifying Actions entitlement and branch protection.
 
-### How skills work
+## Common Delivery Workflows
 
-- **Canonical skills** live in `.agent-kit/skills/` as markdown checklists agents load for a task type.
-- **Runtime wrappers** in `runtime-skills/*/SKILL.md` expose the same content to Antigravity and other skill-directory runtimes.
-- **Roster routing** in `.agent-kit/agent-roster.json` maps `defaultFor` keywords and workflows to agents and their default skill sets—slash commands and natural-language requests both use the same contract.
+### Plan and record a feature
 
-## How Agentic Coders Should Use It
+```bash
+npx agent-kit session start "Add organization invitations" --workflow core-change
+npx agent-kit session decision "Keep authorization in Supabase RLS and server-side mutation boundaries."
+npx agent-kit session handoff \
+  --from planner \
+  --to lead-architect \
+  --decision "Review the invitation data and auth boundaries." \
+  --risk "Invitation tokens and tenant isolation require explicit review."
+npx agent-kit session artifact --file SPEC.md
+npx agent-kit session verify \
+  --command "npm test" \
+  --result pass \
+  --notes "Invitation unit and regression tests passed."
+npx agent-kit session render
+npx agent-kit session close --status complete
+```
 
-Start with the installed files:
+### Record several events at once
+
+```json
+{
+  "events": [
+    {
+      "type": "decision",
+      "agent": "lead-architect",
+      "text": "Use a server action for the mutation and RLS for authorization."
+    },
+    {
+      "type": "artifact",
+      "agent": "nextjs-engineer",
+      "path": "app/invitations/actions.ts"
+    },
+    {
+      "type": "verification",
+      "agent": "qa-engineer",
+      "command": "npm test",
+      "result": "pass",
+      "notes": "Regression suite passed."
+    }
+  ]
+}
+```
 
-- `AGENTS.md`: the high-level operating instructions.
-- `.agent-kit/agent-roster.json`: the machine-readable source of truth for agent routing.
-- `AGENT_ROSTER.md`: the human-readable roster summary.
-- `SKILLS.md`: when each reusable skill should be used.
-- `MODEL_ROUTING.md`: model-profile guidance for each agent and IDE.
-- `QUALITY_GATES.md`: what separates baseline setup, strong delivery, and best-practice evidence.
-- `DESIGN.md`: the frontend design and content contract.
-- `MESSAGING.md`: the positioning, value proposition, proof, objections, voice, and CTA contract.
-- `COUNCIL.md`: where meaningful handoffs and decisions are recorded.
+```bash
+npx agent-kit session checkpoint --file .agent-kit/checkpoint.json
+npx agent-kit session render
+```
 
-Default routing:
+### Review a frontend change
 
-- 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, 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.
+Use the installed command instructions as prompt prefixes in compatible coding tools, or as native commands after activating Antigravity:
 
-For meaningful multi-agent work, record the decision, risk, next handoff, required outputs, and verification evidence in `COUNCIL.md` or `.agent-kit/council-sessions/*.json`.
+```text
+/frontend Build the account settings workflow.
+/ui-audit Review the implementation against the product-quality gates.
+/responsive-cleanup Verify 390px, tablet, and desktop layouts.
+/accessibility-pass Check keyboard, focus, labels, contrast, and error recovery.
+/screenshot-critique Compare desktop and mobile screenshots against DESIGN.md.
+```
 
-## CLI Reference
+The UI detector checks include concrete replacements:
 
-Every command accepts `--json` for machine-readable output. Mutating commands (`init`, `update`, `add skill`, `correction apply`) also accept `--dry-run`.
+| Avoid | Prefer |
+| --- | --- |
+| Thick colored side rails and gradient borders on cards | Quiet 1px full borders, semantic icons, labels, and subtle state tint |
+| Purple/blue gradient heroes and glowing blobs | Product imagery, real workflow screenshots, concrete content, or tokenized neutral surfaces |
+| Decorative card grids | Tables, lists, forms, timelines, split panes, and task-specific grouping |
+| Invented metrics and placeholder charts | Real data, clearly labelled samples, empty states, or connection prompts |
+| "Supercharge your workflow" and similar copy | Specific actions, product nouns, constraints, and supported outcomes |
+| Decorative badge or icon walls | Real integrations, security posture, support details, commands, states, and navigation |
+| Frosted oversized panels | Normal surfaces, practical density, and clear section boundaries |
+| Color-only status | Semantic text, icons, accessible contrast, ARIA state, and recovery actions |
 
-### Install and upgrade
+Exceptions for an established brand system should be recorded in `DESIGN.md` or `.agent-kit/overrides.json`.
 
-| Command | Purpose |
-| --- | --- |
-| `init` | Install docs, roster, skills, schemas, Cursor rules, and project context |
-| `diff` | Compare local docs against bundled templates |
-| `update` | Hash-aware upgrade: pristine docs refresh, local edits kept, conflicts for review |
-| `add skill <name>` | Copy one skill into `.agent-kit/skills/` |
-| `onboard` | Print the recommended first-run checklist |
+### Review Supabase auth or RLS work
 
-```bash
-agent-kit init --stack next-supabase --guided --dry-run
-agent-kit init --activate cursor --activate codex --no-setup
-agent-kit diff
-agent-kit update --dry-run
-agent-kit add skill ui-improvement-harness
+```text
+/plan Add team-scoped document sharing.
+/security Review tenant isolation, IDOR risk, service-role use, and RLS coverage.
+/test Add cross-tenant read/write denial tests and an authorized happy path.
 ```
 
-`init` flags: `--stack`, `--guided`, `--dry-run`, `--activate <targets...>`, `--setup`, `--no-setup`, `--open`, `--force`, `--json`.  
-`update` flags: `--dry-run`, `--force`, `--json`.
+Required evidence should include:
 
-### Setup and Agent Office
+- Migration and rollback implications.
+- RLS policies at the data boundary.
+- Cross-tenant denial tests.
+- Service-role isolation.
+- Server-side input validation.
+- Explicit failure and empty states.
 
-| Command | Purpose |
-| --- | --- |
-| `setup` | Serve local Agent Office (default) and form wizard at `http://127.0.0.1:9321` |
-| `setup --status` | Print onboarding progress as JSON |
-
-Routes: `/` or `/office` (pixel office, default), `/wizard` (form fallback).
+### Preserve a durable correction
 
 ```bash
-agent-kit setup --open
-agent-kit setup --status
+npx agent-kit correction add --scope project \
+  "Use task-first operational layouts; do not add marketing heroes to authenticated tools."
+npx agent-kit correction list
+npx agent-kit correction apply <correction-id>
 ```
 
-### Audit and validation
+Applied project and agent corrections are loaded before meaningful work. Use `correction retire <id> --reason "..." ` when a rule no longer applies.
 
-| Command | Purpose |
-| --- | --- |
-| `audit` | Readiness report with pass/warn/fail findings |
-| `doctor` | Validate CLI runtime prerequisites |
-| `adapter validate [target]` | Validate IDE/runtime adapter assets (`cursor`, `claude`, `codex`, `copilot`, `antigravity`, `all`) |
-| `package validate` | Source-repo release asset validation (maintainers) |
+### Inspect sessions in Agent Studio
 
 ```bash
-agent-kit audit --json --min-readiness baseline-setup
-agent-kit adapter validate cursor
-agent-kit doctor --json
+npx agent-kit studio export
+npx agent-kit studio serve --open
 ```
 
-Readiness levels: `needs-setup`, `baseline-setup`, `needs-improvement`, `best-practice-candidate`. Use `--min-readiness <level>` in CI.
+- Static export: `.agent-kit/studio/index.html`.
+- Live Studio: `http://127.0.0.1:9331` by default.
+- Live sessions use local append-only events and Server-Sent Events.
 
-### Project context
+## Updating An Existing Install
 
-| Command | Purpose |
-| --- | --- |
-| `context init` | Create or refresh `.agent-kit/project-context.json` |
-| `context scan` | Print inferred context without writing |
-| `context ask` | List unanswered high-value context questions |
-| `context render` | Render `.agent-kit/project-context.md` |
-| `context validate` | Validate context against schema |
-| `context show` | Print current context JSON |
+Preview template drift before applying an update:
 
 ```bash
-agent-kit context init
-agent-kit context validate
+npx agent-kit diff --json
+npx agent-kit update --dry-run --json
+npx agent-kit update
+npx agent-kit audit --min-readiness baseline-setup
 ```
 
-### Council sessions
+Update behavior:
 
-| Command | Purpose |
-| --- | --- |
-| `session start` | Open a council session with workflow routing |
-| `session list` / `session active` | Inspect sessions |
-| `session note` / `decision` / `handoff` | Record collaboration events |
-| `session correct` / `artifact` / `verify` / `output` | Record corrections, files, checks, required outputs |
-| `session checkpoint` | Batch-apply events from a JSON file |
-| `session render` / `session close` | Render Markdown and close the session |
+- Pristine installed files are refreshed.
+- Project-owned edits are preserved.
+- Template changes that collide with local edits are written to `.agent-kit/conflicts/`.
+- `--force` is explicit and should be used only after reviewing the diff.
+- Accepted deviations belong in `.agent-kit/overrides.json`.
+
+Example conflict review:
 
 ```bash
-agent-kit session start "Build checkout flow" --workflow frontend-change
-agent-kit session handoff --from planner --to frontend-design-lead --decision "Start design intake." --risk "Generic UI risk."
-agent-kit session verify --command "npm test" --result pass --notes "Tests passed."
-agent-kit session output "visual QA evidence" --status not-applicable --evidence "No UI change."
-agent-kit session checkpoint --file .agent-kit/checkpoint.json
-agent-kit session render
-agent-kit session close --status complete
+npx agent-kit update --dry-run
+git diff -- .agent-kit/manifest.json
+git status --short .agent-kit/conflicts
 ```
 
-### Optional orchestrator
+## Optional Executable Runtime
 
-| Command | Purpose |
-| --- | --- |
-| `orchestrate validate` | Validate runtime config, roster references, and bounds without provider calls |
-| `orchestrate plan <goal...>` | Compile the offline workflow sequence and approval envelope |
-| `orchestrate run <goal...>` | Start a checkpointed run in an isolated worktree |
-| `orchestrate approve <run-id>` | Approve the current gate and resume |
-| `orchestrate resume <run-id> --decision ...` | Explicitly approve or reject a gate |
-| `orchestrate status [run-id]` | Read persisted run state |
-| `orchestrate cancel <run-id>` | Cancel a paused or local in-process run |
-| `orchestrate export <run-id>` | Render redacted run evidence as Markdown |
-| `provider probe`, `mcp probe` | Explicitly test configured external adapters |
-| `credential set`, `credential delete` | Manage OS-keychain references without CLI value flags |
-
-The runtime may create one approved scoped commit on `agent-kit/<run-id>`. It never merges, pushes, opens a pull request, deploys, or applies migrations. See [RUNTIME_ORCHESTRATION_SCOPE.md](RUNTIME_ORCHESTRATION_SCOPE.md) and [packages/runtime/README.md](packages/runtime/README.md).
-
-### Corrections
-
-| Command | Purpose |
-| --- | --- |
-| `correction list` | List durable project and agent correction rules |
-| `correction add` | Add a correction (`--scope project\|agent\|session`) |
-| `correction apply` | Promote a correction into active rules |
-| `correction retire` | Retire a correction with reason |
-| `correction propose-upstream` | Flag a correction for kit promotion |
+Install both packages locally. The runtime package does not provide the `agent-kit` binary by itself.
 
 ```bash
-agent-kit correction add --scope project "Prefer operational density over hero-style marketing layout."
-agent-kit correction apply --id project-ui-density
+npm install --save-dev \
+  @appsforgood/next-supabase-kit \
+  @appsforgood/agent-kit-runtime
+npx agent-kit orchestrate validate
 ```
 
-### Studio views
+Fresh installs include a disabled `.agent-kit/orchestrator.json`. Configure provider model IDs that you have verified for the current provider account. Credentials must be references, not inline secret values.
+
+Minimal configuration example:
+
+```json
+{
+  "schemaVersion": 1,
+  "enabled": true,
+  "defaultWorkflow": "planning",
+  "defaultAlias": "balanced",
+  "providers": {
+    "primary": {
+      "kind": "openai",
+      "credentialRef": "env:OPENAI_API_KEY"
+    }
+  },
+  "modelAliases": {
+    "balanced": {
+      "requiredCapabilities": ["text", "tools"],
+      "maxAttempts": 1,
+      "candidates": [
+        {
+          "provider": "primary",
+          "model": "replace-with-a-verified-provider-model-id"
+        }
+      ]
+    }
+  }
+}
+```
 
-| Command | Purpose |
-| --- | --- |
-| `studio export` | Generate self-contained static HTML at `.agent-kit/studio/index.html` |
-| `studio serve` | Live localhost Agent Office with SSE session events (default port `9331`) |
+Validate and inspect the plan without calling a provider:
 
 ```bash
-agent-kit studio export
-agent-kit studio serve --open
+npx agent-kit orchestrate validate
+npx agent-kit orchestrate plan "Review the authorization boundary" --workflow planning
 ```
 
-### Research (maintainers)
-
-Requires `GITHUB_TOKEN` in the environment.
+Start and manage a run:
 
 ```bash
-agent-kit research discover --limit 100
-agent-kit research scan
-agent-kit research summarize
-agent-kit research propose-updates
+npx agent-kit orchestrate run "Implement the approved authorization fix" --workflow core-change
+npx agent-kit orchestrate status
+npx agent-kit orchestrate approve <run-id>
+npx agent-kit orchestrate resume <run-id> --decision approve
+npx agent-kit orchestrate export <run-id> --output .agent-kit/runtime-export.md
 ```
 
-## What Gets Installed
+Reject or cancel:
 
-Root markdown docs:
+```bash
+npx agent-kit orchestrate resume <run-id> --decision reject
+npx agent-kit orchestrate cancel <run-id>
+```
 
-```text
-AGENTS.md
-AGENT_ROSTER.md
-ASSISTANT_ADAPTERS.md
-COUNCIL.md
-SKILLS.md
-SPEC.md
-DECISIONS.md
-DOCS.md
-DESIGN.md
-MESSAGING.md
-MODEL_ROUTING.md
-QUALITY_GATES.md
-STYLE_GUIDE.md
-SECURITY.md
-TESTING.md
-DEPLOYMENT.md
-UPGRADE.md
-```
-
-The `.agent-kit/` folder includes:
-
-- `agent-roster.json` for default workflow routing.
-- `model-routing.json` for provider-neutral model profile routing.
-- `project-context.json`, `project-context.md`, `corrections/`, and `council-sessions/` for local Agent Studio context, correction rules, session events, and rendered transcripts.
-- `schemas/` for agent roster, council-session, model-routing, project context, correction rules, session events, studio sessions, and audit-report contracts.
-- `agents/`, `skills/`, `runtime-skills/`, `prompts/`, and `checklists/`.
-- `assistant-adapters/` for Codex/AGENTS.md-compatible tools, GitHub Copilot/VS Code, Cursor, Claude Code, and Antigravity.
-- `antigravity/` for native command and plugin assets.
-- `design-briefs/` for SaaS, admin, marketplace, content, tool, ecommerce, portfolio/venue, education, community/social, and AI workflow surfaces.
-- `profiles/` for product-type and adjacent-stack adaptation.
-
-## AI Mechanisms
-
-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`, `/spec`, `/audit`, `/plan`, `/handoff`, `/frontend`, `/test`, `/review`, 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.
-- Local Agent Studio: `.agent-kit/project-context.*`, `.agent-kit/corrections/*.json`, and `.agent-kit/council-sessions/*` keep context, corrections, decisions, handoffs, required-output status, artifacts, verification, and rendered Markdown transcripts local.
-- Tools and MCP: `ASSISTANT_ADAPTERS.md` records browser, GitHub, Figma, Supabase, docs, or other connector setup.
-- Hooks and CI: optional local enforcement plus `agent-kit audit`, tests, install smoke, SBOM, and release gates.
-
-Some IDEs can partially enforce model settings; others only let project files advise the user. The kit records that difference instead of pretending every tool can force per-agent model selection.
-
-Runtime command files are adapters only. `AGENTS.md`, `.agent-kit/agent-roster.json`, `QUALITY_GATES.md`, and Agent Studio session evidence remain the canonical operating model.
-
-## Frontend Quality Bar
-
-The kit is intentionally strict about frontend work because normal AI output often looks generic.
-
-Significant UI work should prove:
-
-- Brand/content intake and real user needs.
-- A selected creative direction, with rejected alternatives.
-- Reference lessons and anti-references without copied source designs.
-- First-screen proof that the real product task, object, workflow, or content is visible.
-- A content fingerprint: real product nouns, labels, data shapes, actions, and edge cases.
-- Asset provenance for real, generated, licensed, and placeholder visuals.
-- Product-quality scorecard evidence.
-- Desktop, mobile, key states, accessibility, and visual QA evidence.
-
-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:
-
-- OWASP Top 10 review for auth, API, Server Action, external-call, upload, and dependency changes.
-- Supabase RLS at the data boundary.
-- Service-role keys isolated to trusted server code.
-- Input validation and safe output rendering.
-- IDOR, SSRF, injection, broken auth, and misconfiguration review.
-- Dependency audit before release.
+Probe external adapters explicitly:
 
-## Updating An Existing Install
+```bash
+npx agent-kit provider probe
+npx agent-kit provider probe primary
+npx agent-kit mcp probe project-tools
+```
 
-Use the upgrade flow instead of overwriting project-owned docs:
+Store a keychain-backed credential through a masked prompt:
 
 ```bash
-agent-kit diff
-agent-kit update --dry-run
-agent-kit update
-agent-kit audit --min-readiness baseline-setup
+npx agent-kit credential set keychain:team-openai
+npx agent-kit credential delete keychain:team-openai
 ```
 
-Document accepted local deviations in `.agent-kit/overrides.json`. Record version changes, conflicts, migration impact, rollback notes, and verification evidence in `UPGRADE.md`.
+### Runtime boundaries
 
-## Research Evidence
+- Mutations occur in an isolated Git worktree.
+- Docker mutation containers use a read-only root, dropped capabilities, `no-new-privileges`, resource limits, and no network by default.
+- File tools reject traversal, symlink escapes, Git internals, environment files, private keys, package-manager credentials, and runtime evidence paths.
+- Network, host execution, worktree writes, and final commits require applicable approval gates.
+- One approved scoped commit may be created on `agent-kit/<run-id>`.
+- The runtime never merges, pushes, opens a pull request, deploys, or applies a migration automatically.
 
-The repo includes a 100-repo research workflow plus focused follow-up summaries.
+See [Runtime orchestration scope](RUNTIME_ORCHESTRATION_SCOPE.md) and the [runtime package README](packages/runtime/README.md) for provider, MCP, sandbox, checkpoint, and recovery details.
 
-Research volume does not count as proof by itself. A repeated pattern only becomes part of the kit when it is promoted into installed assets, audit checks, tests, release gates, schemas, workflows, or documented decisions.
+## Installed Project Contract
 
-Useful evidence files:
+Important root documents:
 
-- `BEST_PRACTICE_EVIDENCE.md`: maps research signals to enforceable assets and validation paths.
-- `research/summaries/`: public-safe research summaries.
-- `research/proposed-updates.md`: promoted and future updates.
-- `DOGFOOD.md`: public-safe downstream adoption evidence.
-- `ROADMAP.md`: the phased done/left tracker.
-
-Research commands:
+| File | Purpose |
+| --- | --- |
+| `AGENTS.md` | High-level operating instructions and required handoffs |
+| `AGENT_ROSTER.md` | Human-readable specialist ownership |
+| `SPEC.md` | Current functional and technical contract |
+| `DECISIONS.md` | Architectural decisions and consequences |
+| `DESIGN.md` | Brand, content, UI rules, anti-references, and approved exceptions |
+| `MESSAGING.md` | Audience, positioning, proof, objections, voice, and CTA rules |
+| `QUALITY_GATES.md` | Evidence required for each readiness level |
+| `SECURITY.md` | Auth, data, dependency, secret, and threat boundaries |
+| `TESTING.md` | Unit, regression, smoke, visual, and release evidence |
+| `DEPLOYMENT.md` | Environment, release, rollback, and observability guidance |
+| `UPGRADE.md` | Template and dependency upgrade history |
+
+Important `.agent-kit/` assets:
+
+- `agent-roster.json`: workflow, agent, and handoff contract.
+- `model-routing.json`: provider-neutral model profiles.
+- `project-context.json` and `project-context.md`: current product and architecture context.
+- `corrections/`: durable project and agent rules.
+- `council-sessions/`: structured decisions, handoffs, outputs, and verification.
+- `skills/`, `prompts/`, and `checklists/`: reusable execution and review procedures.
+- `assistant-adapters/`: IDE-specific installation guidance.
+- `schemas/`: validation contracts for installed evidence.
+
+Inspect an example installation:
+
+- [Example project README](examples/next-supabase-installed/README.md)
+- [Example installed tree](examples/next-supabase-installed/tree.txt)
+- [Example audit report](examples/next-supabase-installed/audit-output.json)
+
+## Workflow Instruction Index
+
+The kit includes 20 lifecycle and UI instruction adapters.
+
+| Goal | Instruction |
+| --- | --- |
+| Capture project context | `/setup` |
+| Define behavior and constraints | `/spec` |
+| Plan implementation and handoffs | `/plan` |
+| Record agent ownership changes | `/handoff` |
+| Build or review frontend work | `/frontend` |
+| Audit kit readiness | `/audit` |
+| Add verification evidence | `/test` |
+| Review code before merge | `/review` |
+| Review auth, data, secrets, and dependencies | `/security` |
+| Review public or conversion copy | `/copy` |
+| Verify release and rollback evidence | `/ship` |
+| Review template or dependency upgrades | `/upgrade` |
+| Detect UI quality failures | `/ui-audit` |
+| Improve an implemented UI | `/ui-polish` |
+| Repair hierarchy and layout | `/layout-cleanup` |
+| Verify responsive states | `/responsive-cleanup` |
+| Verify WCAG 2.1 AA behavior | `/accessibility-pass` |
+| Check product-specific visual identity | `/distinctiveness-pass` |
+| Critique screenshot evidence | `/screenshot-critique` |
+| Run a browser QA loop | `/browser-qa` |
+
+These are instruction adapters, not proof of execution. Canonical steps live in `.agent-kit/prompts/lifecycle-command-index.md` and `.agent-kit/prompts/ui-command-index.md`.
+
+## Output And Flag Notes
+
+Use command help as the source of truth:
 
 ```bash
-export GITHUB_TOKEN=ghp_replace_me
-agent-kit research discover --limit 100
-agent-kit research scan
-agent-kit research summarize
-agent-kit research propose-updates
+npx agent-kit --help
+npx agent-kit audit --help
+npx agent-kit session --help
+npx agent-kit orchestrate --help
 ```
 
-Detailed per-repo findings are committed for repository development, but the public npm package ships generalized summaries and promoted decisions only. See `RESEARCH_CITATION_POLICY.md`.
+Commands that expose `--json` include `init`, `audit`, `diff`, `update`, `doctor`, adapter/package validation, most session mutations, corrections, orchestrator commands, provider/MCP probes, and Studio export.
 
-## Public Release And Supply Chain
+Long-running server commands such as `setup` and `studio serve`, interactive credential entry, and maintainer research commands use their documented human output instead.
 
-Public package name:
+Commands that support `--dry-run` include `init`, `update`, and `add skill`. Review each command's `--help` output rather than assuming a global flag.
 
-```text
-@appsforgood/next-supabase-kit
-```
+## Security Defaults
 
-Release expectations:
+The installed contract requires:
+
+- Supabase RLS at the data boundary, not only UI authorization.
+- Service-role credentials in trusted server code only.
+- Input validation and safe output rendering at every boundary.
+- IDOR, SSRF, injection, broken-auth, upload, and misconfiguration review.
+- Explicit loading, empty, error, retry, and success states.
+- Cross-tenant denial tests for tenant-scoped data.
+- Dependency audit and release evidence for dependency changes.
+- No secrets, customer data, or private repository evidence in committed session files.
+
+## Maintainer Verification
+
+For development of this repository:
+
+```bash
+npm install
+npm run build
+npm test
+npm run release:check
+```
 
-- MIT license.
-- Public npm access.
-- npm Trusted Publishing through GitHub Actions OIDC.
-- No long-lived npm publish token for automation.
-- Dependency Review, CodeQL, OpenSSF Scorecard, Dependabot, SBOM validation, and SBOM attestation.
-- Post-publish verification with `npm run publish:verify`.
+`npm run release:check` runs:
 
-The public package identities are `@appsforgood/next-supabase-kit` and `@appsforgood/agent-kit-runtime`. Every release must pass `npm run release:check`. The OIDC workflow publishes runtime before root when needed, attests separate package-rooted SBOMs, verifies both packages from the public registry, and only then creates the matching GitHub release. Registry metadata is the source of truth for the latest published versions.
+- JSON and version consistency checks.
+- TypeScript, ESLint, and Prettier checks.
+- Unit and regression tests with coverage gates.
+- Package build and asset validation.
+- IDE adapter and example-install validation.
+- Install, Studio, setup, and audit-gate smoke tests.
+- Dependency audit.
+- CycloneDX SBOM validation.
+- Root and runtime package dry runs.
 
-## Repository Health
+The release workflow uses npm Trusted Publishing through GitHub Actions OIDC, creates package-rooted SBOM attestations, publishes the runtime before the root package when needed, verifies both packages from the public registry, and creates a GitHub release only after registry verification.
 
-The repo includes issue forms, PR template, labels, CODEOWNERS, Dependabot, CodeQL, Dependency Review, OpenSSF Scorecard, `CODE_OF_CONDUCT.md`, `SUPPORT.md`, `GOVERNANCE.md`, `REPOSITORY_SETTINGS.md`, and `SUPPLY_CHAIN.md`.
+Additional evidence:
 
-These files are tested as public-readiness assets so the package can be maintained as public OSS, not just published as a tarball.
+- [Best-practice evidence map](BEST_PRACTICE_EVIDENCE.md)
+- [Supply-chain policy](SUPPLY_CHAIN.md)
+- [Maintainer release procedure](MAINTAINER_RELEASE.md)
+- [Research citation policy](RESEARCH_CITATION_POLICY.md)
+- [Public support policy](SUPPORT.md)
 
 ## License