Asymmetric.al - Kingdom Impact Platform

A high-performance Next.js 16.4.2 (App Router) Turborepo monorepo for mission-focused organizations, with three apps (apps/admin, apps/donor, apps/missionary) and shared workspace packages (packages/*).

Quickstart

For the optional six-agent GitHub issue-to-develop workflow, use the Samson Codex Cloud guide. node scripts/factory/setup-cloud.mjs installs frozen dependencies and native personal instructions; --verify-only checks existing setup without repair. The coordinator controls native handoffs; setup does not start an issue trial.

1. Install prerequisites: Node.js 24.22.1, Bun 1.4.3, and Git on your PATH.
2. Choose your setup path.

Credential-free Mission Control sandbox

Use this path for a fresh clone, disposable agent environment, or first run when you do not have Supabase credentials yet:

bun run setup:mission-control:cloud
bun run dev:mission-control

Then open http://localhost:3030. The setup command creates gitignored .env.local defaults, installs dependencies with the frozen lockfile, and runs bun run skills:verify.

Hosted Supabase app development

Use this path when you have a Supabase project URL and anon public key:

1. Run setup (creates .env.local on first run if needed, installs dependencies, checks that committed skill mirrors match docs/ai/skills/, then runs repo setup checks):

1. Fill required Supabase values in .env.local if the first run stopped with "missing required env vars", then run setup again.
2. Start dev: bun run dev (or an app-specific script from package.json). For a single surface, bun run dev:donor is typical (donor on port 3000).
3. Optional smoke check: bun run verify (implemented in scripts/verify/index.mjs). Set VERIFY_HTTP=1 and VERIFY_BASE_URL= when you also want HTTP route checks.

Required for hosted Supabase app development: NEXT_PUBLIC_SUPABASE_URL, NEXT_PUBLIC_SUPABASE_ANON_KEY

Optional: Other entries in .env.example (Stripe, demo accounts, etc.)

bun run dev runs all apps via Turbo (turbo run dev). Default HTTP checks in bun run verify use http://localhost:3000 (VERIFY_BASE_URL), so use bun run dev:donor (or point VERIFY_BASE_URL at the app you are running).

Per-app dev commands (from root package.json):

• bun run dev:donor → donor app, port 3000
• bun run dev:admin → admin app, port 3030
• bun run dev:mission-control → Mission Control admin app, port 3030, with Cloud Agent-friendly dev defaults
• bun run dev:missionary → missionary app, port 4000

Cursor Cloud Agent (VM) secrets

For Cursor Cloud Agent runs, set secrets in the Cloud Agent Secrets settings instead of committing values to repo files.

Set these keys in the cloud environment:

• NEXT_PUBLIC_SUPABASE_URL
• NEXT_PUBLIC_SUPABASE_ANON_KEY
• SUPABASE_SERVICE_ROLE_KEY (optional, server-only/admin workflows)

• .env.local stays local-only and is already gitignored.
• Never expose SUPABASE_SERVICE_ROLE_KEY in browser/client code.
• Browser login flows require only NEXT_PUBLIC_SUPABASE_URL + NEXT_PUBLIC_SUPABASE_ANON_KEY.

Mission Control Cloud Agent setup

Use this when a fresh Cursor Cloud Agent, disposable agent environment, or human in the same sandbox needs the Mission Control Dashboard without a real Supabase project.

bun run setup:mission-control:cloud
bun run dev:mission-control

Then open http://localhost:3030. The setup command writes gitignored .env.local defaults, installs dependencies with bun install --frozen-lockfile, and runs bun run skills:verify. The defaults include ASYM_USE_CI_ENV_DEFAULTS=1, SKIP_ENV_VALIDATION=1, E2E_AUTH_BYPASS=true, NEXT_PUBLIC_SUPABASE_URL=https://example.supabase.co, NEXT_PUBLIC_SUPABASE_ANON_KEY=example-anon-key, PAYLOAD_SECRET=cloud-agent-mission-control-placeholder, PLAYWRIGHT_ADMIN_BASE_URL=http://localhost:3030, and PLAYWRIGHT_ADMIN_PORT=3030. Existing explicit E2E_AUTH_BYPASS=false values are preserved unless you pass --force-bypass. Replace placeholders with real Supabase/demo account secrets when testing live auth or hosted data.

Windows

Windows PowerShell 5.1:

powershell -ExecutionPolicy Bypass -File .\scripts\setup.ps1

PowerShell 7+:

pwsh -File .\scripts\setup.ps1

First run creates .env.local. Fill these required values, then re-run the setup: NEXT_PUBLIC_SUPABASE_URL, NEXT_PUBLIC_SUPABASE_ANON_KEY

The script order matches bun run setup on Unix: verify the approved Node.js runtime and pinned Bun version, install dependencies (unless -SkipInstall), run bun run skills:verify, then bun run setup:verify. After pulling changes that touch skills, run bun run skills:verify; if it reports mirror drift, run bun run skills:sync and commit the updated mirrors.

Skip dependency install if you already ran it:

pwsh -File .\scripts\setup.ps1 -SkipInstall

PowerShell script checks (optional)

Install and run PSScriptAnalyzer locally (not required):

Install-Module PSScriptAnalyzer -Scope CurrentUser
Invoke-ScriptAnalyzer -Path .\scripts\setup.ps1, .\scripts\lib\*.ps1

Architecture & Tech Stack

• Framework: Next.js 16.4.2 (App Router, Turbopack in app configs, Instant Navigation via cacheComponents + partialPrefetching) — _optimized for performance_
• UI system: Tailwind CSS 4 + shadcn/ui (Maia theme) + Base UI
• Theme: Light Zinc aesthetic (Zinc/Zinc), shadcn/ui Maia theme
• Database: Supabase (PostgreSQL)
• Auth: Supabase Auth (shared helpers in packages/auth, packages/api)
• Payments: Stripe (donor and related flows)
• State: React 19 + TanStack Query v5
• Animation: motion (v12) and shared UI helpers such as MotionPreset (packages/ui)

UX/UI Standards (Shadcn/UI)

The platform uses a Zinc-oriented light theme (Maia tokens) for desktop and mobile.

Typography

Fonts are loaded per app in each app’s app/layout.tsx through shared next/font/local modules in @asym/ui/fonts:

• Sans / body: Inter
• Display / headings: Syne
• Mono: Geist Mono

Design Tokens

• Padding: Typical main content uses px-4 py-6 sm:px-6 where applied in layouts.
• Borders: Prefer Maia theme tokens (border-border, border-border/60, --radius).
• Motion: MotionPreset and related presets from @asym/lib/motion-presets / @asym/ui.
• Responsive: Mobile-first patterns; sidebar access often uses Sheet/drawer-style navigation.

Chart Standards

• Tokens: Maia chart CSS variables --chart-1 … --chart-5 where used with Recharts.
• Bar charts (where this convention applies): top corner radius [4, 4, 0, 0], maxBarSize={52}, Y-axis label width and tickMargin={8}, short month labels on time axes when dense.

Apps and local routing

Each surface is a separate Next.js app with its own app/ tree and dev port (see Quickstart).

| Surface | Package | Dev port | Notes | | ----------------------- | ---------------------- | -------: | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Donor | @asym/donor | 3000 | Public site + donor dashboard under /donor-dashboard (authenticated areas) | | Admin (Mission Control) | @asym/admin | 3030 | Staff/admin UI; routes live under apps/admin/app/ (e.g. /, /contributions, /crm). Many in-app links use a /mc/... path prefix in the Mission Control shell. | | Missionary | @asym/missionary-app | 4000 | Missionary dashboard; home route / |

Shared auth gating uses createAuthMiddleware from packages/auth/middleware.ts, wired in each app through apps//proxy.ts (exported proxy).

Product planning

The SiteStacker parity program tracks outcome parity and phase dependencies. The Phase 25 Donor Dashboard Depth specification records the ratified donor scope, acceptance criteria, source contracts and qualification gates. It is planning authority, not implemented or activated behavior; its source-owner amendments remain proposed.

Development

Use the per-app dev:* scripts when you only need one surface, or bun run dev / bun run dev:all when you need several (see root package.json).

bun run build and the build: commands compile Eve dependency artifacts without provisioning sandboxes. Hosted admin previews use the same unqualified artifact mode and leave Eve Release Off. Standalone Eve and production service builds retain full qualification; see the build runbook before treating any preview as launch evidence.

For React and Next.js source cleanup, use bun run react-doctor:audit, retain bun run react-doctor:raw, and finish with bun run react-doctor:check. The strict command requires all eight targets to complete with no unexcepted warnings or errors. bun run test:react-cleanup runs the isolated component browser fixtures. See the React Doctor guide for exact exceptions, source-copy integrity, and verification limits.

AI Agent Guidance System

Agent-oriented docs live under docs/ai/:

• Entry point: AGENTS.md — routing rules for all AI agent work
• Stack registry: docs/ai/stack-registry.md — canonical tech stack list
• Working set: docs/ai/working-set.example.md — template for local docs/ai/working-set.md scratch context
• Nia MCP: docs/ai/nia.md — repo-scoped Nia search, MCP setup, and local sync rules
• Monorepo architecture: docs/ai/monorepo-architecture.md — workspace structure
• Rulebooks: docs/ai/rules/* — domain-specific guidelines (frontend, backend, testing, etc.)
• Async QA Foreman: docs/ai/rules/async-qa-foreman.md — optional background /qa-foreman subagent (.cursor/agents/qa-foreman.md) for grind-style verification while the main agent implements.
• OpenSpec Guardian: docs/ai/rules/openspec-guardian.md — optional background /openspec-guardian subagent (.cursor/agents/openspec-guardian.md) for prompt intent and OpenSpec alignment while the main agent implements.
• Skills: docs/ai/skills/* — reusable workflow patterns (repo-owned, versioned)

Repo-owned skills (how it fits together): Edit and review skills under docs/ai/skills//SKILL.md. AGENTS.md points agents at those paths for routing. The same content is copied into committed mirrors at .agents/skills/ (Codex-style discovery), .cursor/skills/ (Cursor), and .claude/skills/ (Claude Code) by the sync script so tools can surface them without a personal global install. The singular .agent/skills/ path is not a supported mirror and is rejected by bun run skills:verify. CI runs bun run skills:verify to ensure mirrors match the canonical tree.

Skill scripts (root package.json):

| Command | What it does | | ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | bun run skills:sync | Copies canonical docs/ai/skills/* into .agents/skills/, .cursor/skills/, and .claude/skills/, prunes stale canonical copies from mirrors, and overlays extra packs from .agents/skills into .cursor/skills where configured. Run after you edit skills under docs/ai/skills/. | | bun run skills:verify | Fails if mirrors drift from canonical sources or the git tree is dirty after sync (same check used in CI and in bun run setup / scripts/setup.ps1). | | bun run skills:refresh-upstream | Vendors the pinned set into docs/ai/skills/: supabase, supabase-postgres-best-practices, and npm-deps-cleanup from repo-local .agents/skills/ (after targeted Skills CLI refreshes); the paid animations.dev skill emil-design-engineering from $HOME/.cursor/skills/ (after the installer); Cursor Team Kit skills from cursor/plugins; and babysit from a5c-ai/babysitter-cursor. Use the matching upstream workflow for each skill, then run skills:sync / skills:verify (see below). | | bun run skills:refresh-emilkowalski | Promotes the public emilkowalski/skills pack from .agents/skills/ into docs/ai/skills/, preserving Core overlays. Copy upstream trees first and vendor skills/prototype/ as emil-prototype. Do not blindly run npx skills add emilkowalski/skills -y. | | bun run skills:refresh-jakubkrehel | Promotes the jakubkrehel/skills polish pack (better-*, interface-review) from .agents/skills/ into docs/ai/skills/, preserving Core overlays. Use targeted --skill adds; do not vendor unlisted pack skills. | | bun run skills:refresh-frontend-design | Promotes Anthropic frontend-design from .agents/skills/ into docs/ai/skills/, preserving the explicit-only overlay. | | bun run skills:refresh-taste-skill | Promotes design-taste-frontend and redesign-existing-projects from leonxlnx/taste-skill, preserving explicit-only overlays. | | bun run skills:refresh-obra-tdd | Promotes obra Superpowers test-driven-development from .agents/skills/ into docs/ai/skills/. Core TDD remains Matt Pocock tdd. |

Manual-vendored skills: docs/ai/skills/resend-cli/, docs/ai/skills/bendc-frontend-guidelines/, docs/ai/skills/payload/, and docs/ai/skills/cms-migration/ are not part of skills:refresh-upstream. Refresh them from the source documented in each references/upstream.md, then run bun run skills:sync and bun run skills:verify.

ReUI Pro: ReUI agent setup covers authenticated MCP, live documentation, and shared base-maia installs. Run bun run verify:reui --live with the runtime REUI_LICENSE_KEY to check Pro discovery and registry access. bun run skills:refresh-reui stages the current official skill bundle for review; reconcile it into docs/ai/skills/reui/, then sync and verify the mirrors.

When you add or change a skill only under docs/ai/skills/:

bun run skills:sync
bun run skills:verify

Commit both the canonical files and any mirror updates.

Updating vendored skills from upstream (maintainers / periodic refresh):

1. Use targeted Skills CLI refreshes only, such as npx skills add supabase/agent-skills -y, npx skills add anthonyshew/dotfiles -y, or npx skills add mattpocock/skills -y; these update .agents/skills/* and skills-lock.json for packages tracked by the Skills CLI.
2. Do not use npx skills check as a read-only check. In [email protected], that subcommand was observed to update project skills; treat it like skills update and review or revert the generated diff.
3. curl -s "https://animations.dev/api/activate-design-engineering?email=" | bash — updates the upstream-installed emil-design-engineering skill under ~/.cursor/skills/.
4. bun run skills:refresh-upstream — vendors the refreshed copies into docs/ai/skills/supabase, docs/ai/skills/supabase-postgres-best-practices, docs/ai/skills/npm-deps-cleanup, docs/ai/skills/emil-design-engineering, Cursor Team Kit skill directories, and docs/ai/skills/babysit (reconcile any repo-specific notes in those trees if the vendor copy overwrote them; see scripts/refresh-upstream-skills.mjs).
5. Follow references/upstream.md for manual-vendored skills such as Resend CLI, Payload CMS, and bendc frontend guidelines.
6. bun run skills:sync then bun run skills:verify — refresh mirrors and confirm a clean tree.

Updating the vendored Resend CLI skill from upstream (maintainers / on CLI releases):

1. Replace docs/ai/skills/resend-cli/ with the skills/resend-cli/ directory from the desired resend/resend-cli tag (see docs/ai/skills/resend-cli/references/upstream.md).
2. bun run skills:sync then bun run skills:verify.

Package Manager

This repo uses Bun pinned in root package.json packageManager and .bun-version (currently 1.4.3). Install that exact version locally (bun run verify:bun-version after setup). Prefer bun / bunx for scripts in this workspace; CI installs with bun ci. Apps still run on Node.js 24 (CI pins 24.22.1) via Next.js (next build / next start). Do not use bun --bun, and do not add bunVersion to apps/*/vercel.json — that switches Vercel Functions onto the Bun runtime (changelog), which is not this repo’s deploy path.

Monorepo Workspace Contract

Vercel installs with bunx [email protected] install --cwd ../.. --frozen-lockfile to keep the build-image package manager on the workspace pin. See CI toolchain guidance.

Bun workspaces + Turborepo:

apps/*       -> deployable applications (admin, donor, missionary)
packages/*   -> shared libraries used by apps
packages/env -> @asym/env (shared env schema)
tooling/*    -> eslint/tsconfig and other tooling packages

Placement:

• App-specific routing/UI → apps/*
• Shared across apps → packages/*
• Shared env validation → packages/env
• Lint/tsconfig-only packages → tooling/*

• Workspace package names use @asym/ (admin app is @asym/admin, missionary app is @asym/missionary-app).
• Internal deps use workspace:* (not file:).
• Exception: the native PDF Studio migration intentionally consumes the five

• Workspace globs in root package.json: apps/, packages/, packages/env, tooling/*.

bun run verify:workspace-contract

Verify (bun run verify):

• Runs workspace contract checks (and optional HTTP checks).
• VERIFY_HTTP=1 checks /, /login, and /register against VERIFY_BASE_URL (default http://localhost:3000).
• VERIFY_SUPABASE=1 runs bun run setup:verify.

Linting

• apps/* → @asym/eslint-config/nextjs.mjs
• packages/* → @asym/eslint-config/library.mjs where configured
• Root eslint.config.mjs orchestrates

bun run lint

Details: tooling/eslint-config/README.md.

UI lint uses one shared six-rule policy in the three apps, shared UI, and missionary package. For scoped checks, raw legacy findings, discovery health, and suppression pruning, follow the Core design-system lint workflow.

How to add a new app

1. Add apps// with package.json named @asym/ (follow existing naming patterns).
2. Use workspace:* for internal dependencies.
3. Add dev, build, lint, typecheck scripts for Turbo.
4. Use a unique dev port if developers run multiple apps together (see existing apps).
5. Wire auth via apps//proxy.ts if the app should match donor/admin/missionary patterns.
6. Run bun run verify:workspace-contract.

{
  "name": "@asym/my-new-app",
  "private": true,
  "scripts": {
    "dev": "next dev --port 3010",
    "build": "next build",
    "lint": "eslint .",
    "typecheck": "tsc --noEmit"
  },
  "dependencies": {
    "@asym/ui": "workspace:*"
  }
}

How to add a new package

1. packages// with name: "@asym/".
2. Export from the package entry; import by package name across the workspace.
3. workspace:* for internal deps.
4. bun run verify:workspace-contract.

{
  "name": "@asym/my-new-package",
  "version": "0.0.0",
  "private": true,
  "type": "module",
  "exports": {
    ".": "./src/index.ts"
  },
  "dependencies": {
    "@asym/config": "workspace:*"
  }
}

Common commands:

• bun run format / bun run format:check, bun run lint, bun run typecheck
• bun run build (CI-style env via scripts/run-with-ci-env.mjs), bun run build:strict, bun run test:unit
• bun run test:e2e, bun run test:e2e:strict, bun run test:e2e:ui
• bun run verify (optional VERIFY_HTTP=1, VERIFY_SUPABASE=1)
• bun run verify:e2e
• bun run verify:shadscan (locked workspace audit, independent app floors and reviewed evidence; guide)
• Canonical PR/push-readiness gate: bun run ci:preflight (routine development skips full compilation; dependency/build changes compile affected apps). Full QA/release checkpoint: bun run ci:preflight -- --full.

Git Hooks Setup

Husky hooks:

• pre-commit: lint-staged, then the locked Shadscan gate against the staged snapshot
• pre-push: bun run ci:preflight; production-targeting pushes always select --full.

If hooks cannot find tools, configure PATH for Husky (see Husky docs). Example init snippet (adjust for your Node/Bun install):

macOS/Linux:

mkdir -p ~/.config/husky && echo 'export PATH="/usr/local/bin:$PATH"' > ~/.config/husky/init.sh

Windows (Git Bash):

mkdir -p ~/.config/husky && echo 'export PATH="/c/Program Files/nodejs:$PATH"' > ~/.config/husky/init.sh

Turborepo (Task Orchestration + Cache)

• bunx turbo run dev / filtered tasks per package
• bunx turbo run lint typecheck build
• bun run format / bun run format:check

Build env details: docs/guides/development/build-runbook.md.

For the credential-free Anthropic OSS Scanner image, explicit offline service startup, verification profiles and private report triage, see the OSS Scanner runbook.

Key Dependencies

| Package | Version | Notes | | --------------------- | ------- | ------------------------------------------------------------- | | Next.js | 16.4.2 | App Router + Turbopack in app configs | | React | 19.3.1 | | | TypeScript | 7.0.2 | Native workspace compiler; root TS 6 API/editor compatibility | | motion | 12.x | Animation (successor to framer-motion) | | @tanstack/react-query | 5.x | Server state | | @supabase/ssr | 0.8.x | Supabase server/client helpers | | @sentry/nextjs | 10.x | Error monitoring (via @asym/lib, etc.) |

Verification Steps

bun run format
bun run ci:preflight
bun run test:e2e
bun run validate:full
bun run build:strict
bun run test:e2e:strict
bun run verify:t1
bun outdated

Supabase schema + money-unit QA (separate from T1)

bun run verify:supabase-money

verify:money-units samples columns via the Supabase REST API (see scripts/verify-money-units.ts and README notes in-repo for column list and exit codes).

Key Conventions

1. RSC first: Keep components as React Server Components unless interactivity requires client hooks or browser-only APIs.
2. Next.js 16.4.2 compliance: Always await dynamic params and searchParams in routes and layouts (follow current App Router patterns for this repo’s Next version).
3. Zinc and shadcn/ui Maia aesthetic: Maia/Zinc tokens and shared UI patterns in @asym/ui; use zinc-900 for primary actions and zinc-500 for secondary text where this convention applies.
4. Responsive integrity: Test UI changes on both ~375px (mobile) and ~1440px (desktop) viewports.

App-Connected Development

Hosted Supabase only needs the public URL and anon key in .env.local:

• NEXT_PUBLIC_SUPABASE_URL
• NEXT_PUBLIC_SUPABASE_ANON_KEY

How to request access

Ask a maintainer for the shared dev Supabase URL and anon key. Do not use service-role keys or DB credentials for normal app development.

Demo login (optional)

Demo availability and sign-in go through /api/auth/demo-account (implemented in packages/api, re-exported per app). Configure demo users in .env.local per .env.example / docs/auth/sign-in.md.

Details: docs/auth/sign-in.md.

Supabase CLI Workflow (Hybrid)

bun run supabase -- <supabase-subcommand>

• Uses a global supabase CLI when available.
• Otherwise uses a pinned CLI via npx (see scripts/supabase-cli.mjs).

brew install supabase/tap/supabase
Windows (Scoop):
scoop bucket add supabase https://github.com/supabase/scoop-bucket.git
scoop install supabase

Supabase Demo Seed

• supabase/seed.sql
• supabase/migrations/20260216153000_demo_readonly_rls.sql
• scripts/seed-demo.sh

Local

bun run db:migrate:local
or
bun run seed:demo:local

Hosted (explicit target)

Required env vars (hosted script validates the project ref; default ref is defined in scripts/seed-demo.sh):

• NEXT_PUBLIC_SUPABASE_URL (must match the intended Supabase project)
• SUPABASE_SERVICE_ROLE_KEY
• SUPABASE_DB_URL

bun run db:migrate:hosted
bun run seed:demo:hosted
bun run seed:demo:verify

License

Licensed under AGPL-3.0-only. See LICENSE.

What AGPL means for hosted use

If you run a modified version for users over a network, you must offer them the corresponding source for that version.

Trademarks

The license covers source code, not trademarks. Do not use project names or logos without permission unless a separate policy says otherwise.

Third party software

Attributions for bundled third-party code: THIRD_PARTY_NOTICES.md.

Built with ❤️ for the Kingdom.

Offline shared-font verification

The three Next apps compile their existing fonts from reviewed local assets. After changing fonts or their loaders, run bun run verify:fonts:offline in Linux/WSL with Playwright Chromium installed. The check proves compilation and browser font loading without external network access, plus missing-file failure. See shared font provenance and maintenance for details. Normal preflight, all-app builds and relevant E2E still apply.

Development build checkpoints

Core does not automatically deploy merges into develop. Use an explicit qa:smoke preview when a feature is ready to review; the preview compiles on GitHub and uploads prebuilt output to Vercel. Routine PRs keep correctness checks without compiling all three apps. Full compilation remains required for production releases. Existing development URLs serve the last successful deployment until explicitly refreshed. See CI policy.

Imported PDF updates follow the source and artifact refresh workflow. bun run verify:pdf-package-provenance checks the frozen archives and extracted files offline and runs in normal preflight.