@appsforgood/next-supabase-kit 0.1.7 → 0.2.0

package/BEST_PRACTICE_EVIDENCE.md

@@ -25,7 +25,7 @@ This repository treats the 100-repo research pass as input, not proof. A practic
 | Frontend acceptance needs a repeatable product-quality threshold. | Focused follow-up review of design-system, service-design, component-state, and accessibility guidance showed that good primitives do not prove product-specific quality. | Score significant UI work against user/task fit, content specificity, visual identity, information architecture, component states, accessibility and interaction, and source safety. | `skills/frontend-product-quality-rubric.md`, `prompts/frontend-product-quality-scorecard.md`, `checklists/frontend-product-quality.md`, `templates/next-supabase/DESIGN.md`, `rosters/next-supabase-default-council.json`. | Frontend-change roster requirements, `agent-kit audit`, public-readiness tests, install smoke. |
 | Visual QA needs a path beyond manual taste review. | Follow-up visual-testing review identified Storybook, Playwright screenshots, Chromatic, Argos, Loki, and baseline evidence as repeatable patterns. | Provide visual QA tiers that scale from screenshot review to regression evidence. | `skills/visual-regression-qa.md`, `checklists/visual-regression.md`, `prompts/visual-qa-plan.md`, `templates/next-supabase/TESTING.md`. | Public-readiness tests, `QUALITY_GATES.md` maturity evidence, downstream visual QA artifacts. |
 | Public OSS maintainability needs more than a package tarball. | Repository-health follow-up identified structured intake, ownership, labels, support, and governance as durable signals. | Ship contributor intake, labels, CODEOWNERS, support, conduct, governance, and repository settings guidance. | `.github/ISSUE_TEMPLATE/*`, `.github/pull_request_template.md`, `.github/CODEOWNERS`, `.github/labels.yml`, `SUPPORT.md`, `GOVERNANCE.md`, `REPOSITORY_SETTINGS.md`. | Public-readiness tests, PR labeler workflow, documented branch and repository settings. |
-| Supply-chain trust must be visible before publish. | Supply-chain follow-up identified OIDC publishing, provenance, dependency review, Scorecard, SBOMs, workflow controls, and release gates. | Use Trusted Publishing, avoid long-lived npm publish tokens, generate and attest a CycloneDX SBOM for the package tarball, and verify release integrity before publish. | `.github/workflows/release.yml`, `.github/workflows/scorecard.yml`, `.github/workflows/dependency-review.yml`, `SUPPLY_CHAIN.md`, `scripts/release-check.mjs`, `scripts/sbom-check.mjs`. | `npm run release:check`, `npm run sbom:check`, OpenSSF Scorecard, Dependency Review, npm Trusted Publishing, SBOM attestation, pack dry run. |
+| Supply-chain trust must be visible before publish. | Supply-chain follow-up identified OIDC publishing, provenance, dependency review, Scorecard, SBOMs, workflow controls, and release gates. | Use Trusted Publishing, avoid long-lived npm publish tokens, generate and attest a package-rooted CycloneDX SBOM for every tarball, and verify each public package before creating the source release. | `.github/workflows/release.yml`, `.github/workflows/scorecard.yml`, `.github/workflows/dependency-review.yml`, `SUPPLY_CHAIN.md`, `scripts/release-check.mjs`, `scripts/sbom-check.mjs`. | `npm run release:check`, root/runtime SBOM checks, OpenSSF Scorecard, Dependency Review, npm Trusted Publishing, SBOM attestations, pack dry runs. |
 | Best-practice claims need a maturity model. | Follow-up review showed a green build alone does not prove best-practice readiness. | Separate setup validity from project evidence and best-practice candidacy. | `templates/next-supabase/QUALITY_GATES.md`, `schemas/audit-report.schema.json`, `skills/best-practice-maturity-review.md`, `src/install/audit.ts`. | `agent-kit audit --min-readiness`, audit-report schema validation, install smoke, release check. |
 | Downstream adoption evidence must stay current. | Current read-only dogfood audits of two older installs both produced `11 pass / 20 warn / 7 fail`, proving that later hardening made older installs drift below baseline setup. | Publish a sanitized dogfood summary and keep detailed local-path evidence repo-only. Treat stale dogfood findings as upgrade inputs. | `DOGFOOD.md`, `dogfood/*.md`, `UPGRADE.md`, `agent-kit audit`, `agent-kit update`, `tests/public-readiness.test.ts`. | Public-readiness tests, release check, read-only dogfood audit snapshots, package dry run. |
 | Older installs need a conflict-safe upgrade proof. | Dogfood audits showed both older installs lacked current roster schemas, assistant adapters, maturity gates, upgrade docs, and design critique assets. | Add a deterministic old-install fixture that proves diff previews missing/conflicting assets and update adds missing current assets while preserving customized docs through conflicts. | `tests/update.test.ts`, `src/install/diff.ts`, `src/install/install.ts`, `UPGRADE.md`, `DOGFOOD.md`. | Unit tests, audit report on upgraded fixture, release check. |

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## 0.2.0
+
+- Ship the leading-harness release: hash-aware manifest v2 updates, audit v2 with SARIF and suppressions, hardened localhost Agent Studio APIs, and optional executable council workflows through `@appsforgood/agent-kit-runtime`. Runtime workflows use validated roster routing, SQLite checkpoints, explicit approval gates, provider and allowlisted MCP adapters, Docker-first tools, isolated Git worktrees, bounded retries/timeouts, cancellation, redacted evidence, and scoped commits. Release automation now publishes and verifies the runtime and root packages with separate SBOM attestations before creating a GitHub release.
+
+## 0.1.9
+
+- Added explicit anti-slop UI rules for frontend work, including accent-border cards, gradient-as-design, card soup, fake dashboard proof, vague SaaS sayings, decorative credibility, oversized glass panels, ornamental icon walls, filler sections, and inaccessible decorative state styling.
+- Extended installed template design guidance, UI detectors, frontend quality checklist, and review prompts with concrete best-practice replacements for generic AI-looking UI patterns.
+
+## 0.1.8
+
+- Added `tests/setup-server-api.test.ts` for full setup-server API route coverage (PATCH state, context import, checklists, design/messaging drafts, apply, agentic-level refresh, oversized body, 404) plus wizard draft edge cases.
+- Moved `readJsonBody` to `src/studio/shared.ts` for reuse; setup-server validates invalid `completeSection` ids with 400.
+- Added Playwright UI screenshot smoke (`scripts/smoke-ui-screens.mjs`, `npm run smoke:ui-screens`, Playwright 1.55.1) with dedicated Ubuntu CI job uploading `artifacts/ui-screens/` (not in `release:check`).
+- Completed Agent Studio Milestone 8: `POST /api/sessions/:id/note` and `/render` on studio serve, session picker, note form, and render button in live office UI; SSE broadcast for notes.
+- Updated `TESTING.md`, `QUALITY_GATES.md`, `DOCS.md`, `ROADMAP.md`, and `DECISIONS.md` for studio serve endpoints, UI smoke, and runtime adapter references.
+
 ## 0.1.7
 
 - Added **Workflow Commands** section to README and docs site: lifecycle diagram, 12 core + 8 UI slash commands, council table, skills-by-phase grouping, and explicit separation from package CLI commands.

package/DOGFOOD.md

@@ -34,6 +34,17 @@ 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-04 Publish @0.1.8 Snapshot
+
+Date: 2026-07-04
+CLI source: local `dist/index.js` after `npm run release:check`
+
+- Setup-server API route coverage (`tests/setup-server-api.test.ts`), Playwright UI screenshot smoke (`smoke:ui-screens`, Playwright 1.55.1), and Agent Studio Milestone 8 completion (note/render POST endpoints, session picker, live office controls).
+- `readJsonBody` shared between setup and studio servers; oversized bodies return 400 without dropping the connection; studio SSE broadcasts notes.
+- Dedicated Ubuntu CI job for UI screenshots; not part of `release:check` matrix.
+- Local verification: `release:check` green (150 tests, setup-server.ts 86% statements), `smoke:ui-screens` produced 4 PNGs.
+- Published `@appsforgood/next-supabase-kit@0.1.8`; `publish:verify` passed against live registry.
+
 ## 2026-07-04 Publish @0.1.7 Snapshot
 
 Date: 2026-07-04
@@ -172,5 +183,5 @@ Scope: README/docs discoverability + three new Antigravity adapters
 | Canonical index | `prompts/lifecycle-command-index.md` for delivery commands (parallel to `prompts/ui-command-index.md`) |
 | New adapters | `/spec`, `/test`, `/review` in `antigravity/commands/` (20 total native commands) |
 | Roster | `testing` and `code-review` workflows; planning triggers for spec keywords |
-| Out of scope | `/build`, `/webperf`, `/code-simplify`, `/build auto` — documented as future orchestration |
+| Historical scope | `/build`, `/webperf`, `/code-simplify`, and `/build auto` were deferred in this 0.1.7 review; the later runtime ships bounded roster workflows rather than cloning those command semantics |
 | Verification | `npm test`, `agent-kit adapter validate antigravity` after build |

package/README.md

@@ -18,12 +18,14 @@ This is not just a prompt bundle. A project gets machine-readable agent routing,
 
 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.
 
+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.
+
 ## Quick Start
 
-Use this in a Next.js + Supabase project (latest: **v0.1.7** on npm):
+Use the current stable package in a Next.js + Supabase project:
 
 ```bash
-npx @appsforgood/next-supabase-kit@0.1.7 init --stack next-supabase --setup --open
+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
 ```
@@ -42,6 +44,16 @@ npx @appsforgood/next-supabase-kit init --activate cursor --activate antigravity
 npx @appsforgood/next-supabase-kit adapter validate all
 ```
 
+Optional executable orchestration:
+
+```bash
+npm install --save-dev @appsforgood/agent-kit-runtime
+agent-kit orchestrate validate
+agent-kit orchestrate plan "Describe the goal"
+```
+
+`.agent-kit/orchestrator.json` is installed disabled. Configure verified provider model IDs and `env:` or `keychain:` credential references before enabling it.
+
 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
@@ -91,7 +103,7 @@ Twenty slash commands map to the delivery lifecycle. Each one activates the righ
 SETUP → SPEC/PLAN → BUILD → VERIFY → REVIEW → SHIP
 ```
 
-**Workflow commands** (`/setup`, `/spec`, …) are runtime adapters. **Package CLI** commands (`agent-kit init`, `audit`, `session`, …) are documented under [CLI Reference](#cli-reference) below. Cursor loads rules and skills from `init`; Antigravity gets native slash commands from `init --activate antigravity`. See `ASSISTANT_ADAPTERS.md` for per-IDE setup.
+**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
 
@@ -279,6 +291,23 @@ agent-kit session render
 agent-kit session close --status complete
 ```
 
+### Optional orchestrator
+
+| 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 |
@@ -458,7 +487,7 @@ Release expectations:
 - Dependency Review, CodeQL, OpenSSF Scorecard, Dependabot, SBOM validation, and SBOM attestation.
 - Post-publish verification with `npm run publish:verify`.
 
-The package is published to public npm under `@appsforgood/next-supabase-kit@0.1.7`. 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 last passed **2026-07-04** against the live registry: `@0.1.7` doctor, clean init, and `audit --min-readiness baseline-setup` with zero failures.
+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.
 
 ## Repository Health
 

package/REPOSITORY_SETTINGS.md

@@ -30,14 +30,19 @@ Create environment `npm-publish` with:
 
 - Required reviewers enabled.
 - Prevent self-review enabled where available.
-- Deployment branches restricted to `main` and release events.
-- 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.
+- Deployment branches restricted to `main`.
+- No npm package-write token secrets. Automated publication must fail closed when Trusted Publishing is unavailable.
+- Required reviewers should protect manual non-dry-run dispatches without preventing the normal version-PR merge path.
 
-The npm trusted publisher must match:
+Under **Actions > General > Workflow permissions**, allow GitHub Actions to create pull requests. The version workflow has job-scoped `contents: write` and `pull-requests: write` permissions and uses that setting only to open or update the Changesets version PR.
+
+Create this npm Trusted Publisher for each of these package names:
+
+- `@appsforgood/next-supabase-kit`
+- `@appsforgood/agent-kit-runtime`
+
+Each trusted publisher must match:
 
-- Package: `@appsforgood/next-supabase-kit`
 - Provider: GitHub Actions
 - Repository: `lukey662/agentsandskills`
 - Workflow: `release.yml`
@@ -54,6 +59,7 @@ Enable:
 - Dependabot security updates.
 - Code scanning alerts.
 - Secret scanning where available.
+- Push protection for detected secrets where available.
 
 ## Issues, Discussions, And Labels
 

package/SECURITY.md

@@ -16,6 +16,20 @@ Report vulnerabilities through a private security advisory or by contacting the
 - Never overwrite downstream project files unless the user passes an explicit force flag.
 - Redact secrets before writing logs, findings, summaries, or prompts.
 - Do not copy third-party source code from research targets into this package.
+- Keep npm lifecycle scripts deny-by-default where possible; pin reviewed approvals for required native/build packages and deny optional scripts that are not needed.
+
+## Optional Runtime Threat Model
+
+- Treat model output, repository files, MCP metadata, MCP output, and provider error text as untrusted input.
+- Accept credential references only from environment variables or the OS keychain. Never persist resolved values.
+- Reject provider/MCP redirects, embedded URL credentials, unsafe protocols, non-allowlisted MCP hosts, and private or special-use DNS results unless private access is explicit.
+- Require explicit host opt-in and approval for Cursor and stdio MCP. Use argv spawning with no shell and a minimal environment.
+- Reject path traversal, symlink escapes, Git internals, environment files, private keys, package-manager credentials, and runtime evidence paths from model file tools.
+- Block worktree creation when sensitive filenames are tracked. Run the full audit before enabling runtime execution because filename checks do not replace content secret scanning.
+- Keep Docker network off by default and require approval before configured network access. Resolve reviewed local images to immutable IDs.
+- Never authorize an MCP action solely from server annotations or model intent. Empty tool allowlists expose nothing.
+- Redact run records and event logs recursively. Redaction is defense in depth, not permission to send secrets or customer data to a provider.
+- Never auto-merge, push, open pull requests, deploy, or apply migrations.
 
 ## Downstream Security Defaults
 

package/SUPPLY_CHAIN.md

@@ -1,18 +1,18 @@
 # Supply Chain Security
 
-This package is intended for public npm distribution and downstream project bootstrapping. Release integrity is part of the product, not an optional operations detail.
+The root kit and optional runtime are intended for public npm distribution. Release integrity is part of the product, not an optional operations detail.
 
 ## Publish Identity
 
-- Public package: `@appsforgood/next-supabase-kit`.
-- 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.
+- Public packages: `@appsforgood/next-supabase-kit` and `@appsforgood/agent-kit-runtime`.
+- Publish path: GitHub Actions release workflow through npm Trusted Publishing.
+- Authentication: short-lived GitHub OIDC identity only; automated publishing has no npm token fallback.
 - Environment: `npm-publish`.
-- Trusted publisher must be scoped to repository `lukey662/agentsandskills`, workflow `release.yml`, and allowed action `npm publish`.
+- Each npm package must have its own Trusted Publisher scoped to repository `lukey662/agentsandskills`, workflow `release.yml`, environment `npm-publish`, 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. 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 workflow removes inherited npm token variables, supplies a token-free npm configuration, and requires the GitHub OIDC request context before publishing. A missing or incorrect package-level Trusted Publisher fails closed instead of switching authentication modes. Successful publication carries npm provenance tied to that workflow identity.
 
-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.
+The release workflow creates separate root/runtime tarballs and package-rooted CycloneDX SBOMs, uploads them as release evidence, and attests each SBOM against its exact tarball. Runtime publishes before root when both are new. Both public packages are verified before the matching GitHub release, so a partial npm publish cannot create an apparently successful source release.
 
 ## Release Gates
 
@@ -22,16 +22,16 @@ Before publish:
 - `npm run release:check`
 - Public release review
 
-`npm run release:check` validates JSON assets, typechecks, tests, builds, runs install smoke, runs dependency audit, validates SBOM generation, and performs package dry run. The install smoke also inspects packaged public files for forbidden private-package text.
+`npm run release:check` validates JSON assets, typechecks both workspaces, tests, builds both packages, runs install smoke, runs dependency audit, validates SBOM generation, and performs root/runtime package dry runs. The install smoke also inspects packaged public files for forbidden private-package text.
 
 `npm run sbom:check` validates that the lockfile-derived CycloneDX SBOM can be generated, includes runtime dependencies, and has no unresolved required dependency links. Optional platform-specific dependency links may be skipped when npm records optional package edges that are not present for the current install target.
 
 After publish:
 
 - `npm view @appsforgood/next-supabase-kit@<version> version`
-- `npx --yes @appsforgood/next-supabase-kit@<version> doctor`
-- `npx --yes @appsforgood/next-supabase-kit@<version> init --stack next-supabase` in a clean temp project
-- `npx --yes @appsforgood/next-supabase-kit@<version> audit --json` with zero failures
+- `npm view @appsforgood/agent-kit-runtime@<version> version`
+- Clean install and import of `@appsforgood/agent-kit-runtime`
+- Clean install of both packages followed by root `doctor`, `init`, `audit --json` with zero failures, and `orchestrate validate --json`
 
 The release workflow and `npm run publish:verify` both use `scripts/post-publish-verify.mjs` for this post-publish verification path.
 
@@ -39,7 +39,7 @@ The release workflow and `npm run publish:verify` both use `scripts/post-publish
 
 - CI verifies package behavior on push and pull request.
 - Dependency Review blocks pull requests that introduce moderate or worse known vulnerabilities.
-- Dependabot proposes npm and GitHub Actions updates.
+- Dependabot proposes npm and GitHub Actions updates; workflow actions remain pinned to immutable commit SHAs with reviewed version comments.
 - CodeQL scans JavaScript/TypeScript code.
 - OpenSSF Scorecard publishes repository security posture as code-scanning evidence.
 - CODEOWNERS identifies default review ownership for source, templates, schemas, and workflows.
@@ -47,9 +47,10 @@ 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; any fallback token must be scoped for package publishing and stored only as a GitHub Actions secret.
+- Do not use npm publish tokens for automation. Maintainer-local OTP publishing is an explicit recovery operation, not a workflow fallback.
 - 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 fallback publish secrets after Trusted Publishing is confirmed.
+- Keep package-write token secrets absent from repository and environment configuration.
 - 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.
+- Keep `allowScripts` approvals version-pinned to reviewed required native/build packages. Explicitly deny optional package scripts that are not needed.

package/UPGRADE.md

@@ -13,13 +13,13 @@ This file defines how maintainers and downstream projects should upgrade Agent K
 
 Before publishing a new package version:
 
-1. Update `CHANGELOG.md` with user-visible changes, migration notes, and deprecations.
+1. Update changesets plus root/runtime changelogs with user-visible changes, migration notes, and deprecations.
 2. Update `ROADMAP.md` and `BEST_PRACTICE_EVIDENCE.md` when a research finding becomes enforced behavior.
 3. Run `npm run release:check`.
 4. Run `agent-kit package validate` from the source repository when runtime adapter or package assets changed.
-5. Confirm the pack dry run includes only public-safe files.
-6. Publish through npm Trusted Publishing.
-7. Verify public install with `npx @appsforgood/next-supabase-kit`.
+5. Confirm root and runtime pack dry runs include only public-safe files.
+6. Publish runtime then root through npm Trusted Publishing with separate SBOM attestations.
+7. Verify public runtime import plus root `doctor`, `init`, `audit`, and `orchestrate validate`.
 
 ## Downstream Upgrade Checklist
 
@@ -33,6 +33,16 @@ npx @appsforgood/next-supabase-kit@latest adapter validate antigravity
 npx @appsforgood/next-supabase-kit@latest audit --min-readiness baseline-setup
 ```
 
+Projects using executable orchestration should also upgrade the optional runtime deliberately:
+
+```bash
+npm install --save-dev @appsforgood/agent-kit-runtime@latest
+agent-kit orchestrate validate
+agent-kit orchestrate plan "Upgrade verification"
+```
+
+Review `.agent-kit/orchestrator.json` conflict proposals, schema changes, provider capability declarations, MCP/host/private-network exceptions, Docker image availability, native `better-sqlite3` install policy, and checkpoint compatibility before enabling runs. Finish or cancel paused runs before changing runtime versions.
+
 The package includes an older-install regression fixture that exercises this path. The fixture proves update preserves customized docs, writes conflict templates, installs new current baseline docs and `.agent-kit/` assets, then audits with zero failures.
 
 `agent-kit diff` includes an upgrade preview. Review `preview.wouldCreate`, `preview.wouldWriteConflicts`, `agentRoster`, `modelRouting`, and `libraryFolders.missing` before running update so the branch owner knows which files will be created, which local docs will be preserved through conflicts, and which `.agent-kit/` assets will be refreshed.

package/antigravity/plugin.json

@@ -2,7 +2,7 @@
   "schemaVersion": 1,
   "name": "agent-kit-next-supabase",
   "displayName": "Agent Kit Next/Supabase",
-  "version": "0.1.7",
+  "version": "0.1.8",
   "description": "Runtime commands and portable skills for the Agent Kit Next/Supabase council workflow.",
   "homepage": "https://github.com/lukey662/agentsandskills",
   "sourceOfTruth": [

package/assistant-adapters/README.md

@@ -22,8 +22,11 @@ Adapters should point back to those files. Do not maintain separate policy, secu
 - `cursor-agent-kit.mdc`: Cursor project-rule template.
 - `claude-code-subagents.md`: Claude Code project subagent template guidance.
 - `antigravity.md`: Antigravity plugin, command, runtime skill, and validation guidance.
+- `orchestrator-runtime.md`: executable LangGraph runtime, approvals, sandbox, provider, MCP, worktree, and evidence guidance.
 - `model-selection/`: dated setup examples for Codex, Claude Code, Cursor, and GitHub Copilot model routing.
 
 ## Activation Rule
 
 Record active tool surfaces in `ASSISTANT_ADAPTERS.md`. A project is not best-practice ready simply because adapter templates exist; the team must document which tools are active, how model selection is handled, whether enforcement is enforced/partial/advisory/manual, and what evidence proves the canonical council instructions loaded.
+
+IDE adapters are not execution evidence. Claim an orchestrated run only when `agent-kit orchestrate status`, runtime JSONL evidence, and the SQLite checkpointed workflow confirm it.

package/assistant-adapters/antigravity.md

@@ -19,6 +19,8 @@ This adapter packages Agent Kit as native Antigravity-style plugin assets while
 
 Runtime command files must wrap those files. Do not fork role definitions, security policy, frontend quality rules, release gates, or session evidence rules into command prompts.
 
+Antigravity commands are instruction adapters. They do not replace or prove execution by `@appsforgood/agent-kit-runtime`; use `agent-kit orchestrate status` and exported run evidence for that claim.
+
 ## Activation
 
 ```bash

package/assistant-adapters/claude-code-subagents.md

@@ -35,3 +35,4 @@ Start with the Planner workflow. For core changes, hand off to Lead Architect. F
 - Document active subagents and verification evidence in `ASSISTANT_ADAPTERS.md`.
 - Record model-selection evidence and limitations in `ASSISTANT_ADAPTERS.md`.
 - Avoid giving a subagent broader tool access than its role needs.
+- Treat Claude subagents as instruction adapters. Use `agent-kit orchestrate ...` and its run evidence when the task requires the executable checkpointed council.

package/assistant-adapters/codex-agents.md

@@ -49,3 +49,5 @@ Record in `ASSISTANT_ADAPTERS.md`:
 - Any known limitations or manual invocation steps.
 
 Run `agent-kit adapter validate codex` after activation.
+
+Codex custom agents are instruction adapters. Use `agent-kit orchestrate validate`, `plan`, `run`, and `status` when a task requires the executable checkpointed council; do not infer graph execution from a delegated IDE thread.

package/assistant-adapters/cursor-agent-kit.mdc

@@ -26,6 +26,8 @@ Use `AGENTS.md`, `AGENT_ROSTER.md`, `.agent-kit/agent-roster.json`, `MODEL_ROUTI
 
 Run `agent-kit audit --min-readiness baseline-setup` for setup validity. Use `agent-kit audit --min-readiness best-practice-candidate` only when project-specific evidence has replaced starter placeholders.
 
+This Cursor rule is an instruction adapter, not proof that the executable council ran. Use `agent-kit orchestrate validate` and `agent-kit orchestrate status` for runtime evidence. A Cursor executor route additionally requires `cursor.enabled`, `sandbox.allowHostMutations`, an isolated worktree, and explicit host-mutation approval.
+
 ## Model Selection
 
 Use Cursor's active model picker or team model policy with the profile in `MODEL_ROUTING.md`. Treat this rule as advisory unless the active Cursor environment provides enforceable model controls.

package/assistant-adapters/cursor-planner.mdc

@@ -11,4 +11,4 @@ When a request is ambiguous, planning-oriented, roadmap-related, or spans multip
 
 Delegate to the `@planner` subagent in `.cursor/agents/planner.md` when the task needs isolated planning context.
 
-Read project context, corrections, and `AGENT_ROSTER.md` before choosing a workflow.
+Read `AGENTS.md`, `.agent-kit/agent-roster.json`, `MODEL_ROUTING.md`, project context, and active corrections before choosing a workflow.

package/assistant-adapters/orchestrator-runtime.md

@@ -0,0 +1,39 @@
+# Orchestrator Runtime Adapter
+
+`@appsforgood/agent-kit-runtime` is the optional executable layer for the Agent Kit council. IDE rules, subagents, slash commands, and model-routing documents remain instruction adapters; they do not imply that a checkpointed graph ran.
+
+## Activation
+
+```bash
+npm install --save-dev @appsforgood/agent-kit-runtime
+agent-kit orchestrate validate
+agent-kit orchestrate plan "Describe the goal"
+```
+
+Edit `.agent-kit/orchestrator.json`, add provider credential references such as `env:OPENAI_API_KEY` or `keychain:team-openai`, configure at least one deterministic model alias, and set `enabled` to `true` only after validation passes.
+
+## Execution Contract
+
+- Roster workflows compile to explicit, bounded LangGraph nodes.
+- Runs pause at plan, network, worktree-write, host-execution, and final-commit gates when applicable.
+- Mutations occur in an isolated Git worktree. Agent Kit may create one scoped commit after approval; it never merges, pushes, or opens a pull request.
+- Docker is the default mutation command boundary. Network access is off unless configured and approved.
+- Provider and remote MCP requests reject redirects, embedded credentials, non-allowlisted hosts, and private or special-use addresses unless private access is explicitly configured.
+- Stdio MCP servers execute on the host only when both `allowHostExecution` and `sandbox.allowHostMutations` are enabled and the host gate is approved.
+- Run checkpoints live in `.agent-kit/runtime/runtime.sqlite`; redacted run records and JSONL evidence live under `.agent-kit/runtime/runs/` and are ignored by Git.
+
+## Cursor Executor
+
+Set an agent route to `cursor` only when Cursor CLI execution is intentionally required. The runtime invokes argv directly inside the isolated worktree, with no shell, a bounded timeout, minimal inherited environment, and an explicit host-mutation approval. Provider-backed model agents remain the default.
+
+## Verification
+
+Record:
+
+- `agent-kit orchestrate validate --json`
+- the offline `orchestrate plan` output
+- provider and MCP probe results, without credentials
+- run ID, approval decisions, scoped commit, and exported evidence
+- Docker image ID and any private-network or host-execution exception rationale
+
+Use `agent-kit studio serve` to inspect and decide paused runs in the local Studio UI.

package/checklists/frontend-quality.md

@@ -9,6 +9,7 @@
 - Frontend product-quality scorecard is at least adequate before release.
 - Visual direction fits the domain.
 - No generic AI-site gradient/card defaults.
+- No accent-border cards, glow rails, neon strokes, gradient borders, oversized glass panels, ornamental icon walls, fake dashboard proof, decorative credibility badges, vague SaaS sayings, or layout filler sections unless documented as a brand-system exception.
 - Navigation is clear and predictable.
 - Loading, empty, error, disabled, and success states exist.
 - Mobile layout is designed, not incidental.

package/checklists/ui-detectors.md

@@ -60,10 +60,16 @@ Use this deterministic checklist for UI audit, polish, layout cleanup, responsiv
 | Detector | Blocker Signal | Major Signal |
 | --- | --- | --- |
 | Generic SaaS styling | First screen could fit another product by changing logo and headline | Visual direction relies on common cards, gradients, fake dashboards, or vague claims |
+| Accent-border card styling | Cards, callouts, alerts, panels, or status messages rely on thick, high-contrast, one-sided colored borders, glow rails, neon strokes, or gradient borders as the main state cue | Accent borders add decoration where restrained 1px full-border surfaces, subtle background tint, clear labels, icons, and semantic state text would communicate better |
+| Gradient-as-design | Gradient hero, gradient text, abstract blobs, or glow backgrounds substitute for a product-specific first screen | Gradients are present without a tokenized role, brand rationale, or product-specific content support |
+| Card soup | The screen is mostly decorative cards and the primary workflow is unclear | Repeated cards could become a table, list, timeline, form, split pane, or workflow-specific grouped section |
 | Missing content fingerprint | UI hides missing product decisions behind placeholders | Real nouns, records, actions, or edge cases are too sparse |
 | Weak visual identity | No product-specific density, typography, imagery, or interaction point of view | Direction is coherent but category-generic |
 | Unsafe reference use | Copy, assets, layout signature, or brand identity appear copied | References are cited without lessons and anti-copy notes |
 | Fake or unsupported proof | Fake metrics or claims imply unavailable capability | Proof exists but is not tied to actual product behavior |
+| Vague SaaS sayings | Copy could apply to any product and hides what the user can actually do | Phrases like "supercharge your workflow", "unlock insights", "seamless collaboration", or "AI-powered productivity" are not grounded in concrete actions, nouns, constraints, or outcomes |
+| Decorative credibility | Badges, pills, stars, awards, or "trusted by" placeholders imply proof that does not exist | Credibility elements are decorative and should be replaced with real proof, integration names, security posture, support details, or removed |
+| Filler sections | Marketing sections replace the requested app or tool workflow on the first screen | "Features", "benefits", or "how it works" sections are generic and should be replaced with the actual usable workflow or domain-specific hierarchy |
 
 ## Evidence Requirements