@appsforgood/next-supabase-kit 0.1.8 → 0.2.1

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/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