qualia-framework 6.8.1 → 6.9.0

package/templates/stacks/ai-agent/scaffold/lib/supabase/server.ts

@@ -0,0 +1,28 @@
+import { createServerClient } from "@supabase/ssr";
+import { cookies } from "next/headers";
+
+// Server-side Supabase adapter — all mutations and RLS-protected reads.
+export async function createClient() {
+  const cookieStore = await cookies();
+
+  return createServerClient(
+    process.env.NEXT_PUBLIC_SUPABASE_URL!,
+    process.env.NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY!,
+    {
+      cookies: {
+        getAll() {
+          return cookieStore.getAll();
+        },
+        setAll(cookiesToSet) {
+          try {
+            cookiesToSet.forEach(({ name, value, options }) =>
+              cookieStore.set(name, value, options)
+            );
+          } catch {
+            // Server Component context — middleware refreshes the session.
+          }
+        },
+      },
+    }
+  );
+}

package/templates/stacks/ai-agent/scaffold/next.config.mjs

@@ -0,0 +1,7 @@
+/** @type {import('next').NextConfig} */
+const nextConfig = {
+  // API routes are server-only (OpenRouter key never reaches the client).
+  // Add a Railway worker target in Phase 5 if long-running jobs are scoped.
+};
+
+export default nextConfig;

package/templates/stacks/ai-agent/scaffold/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "ai-agent",
+  "version": "0.1.0",
+  "private": true,
+  "scripts": {
+    "dev": "next dev",
+    "build": "next build",
+    "start": "next start",
+    "lint": "next lint",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "next": "^16.0.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "@supabase/supabase-js": "^2.45.0",
+    "@supabase/ssr": "^0.5.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "tailwindcss": "^4.0.0",
+    "@tailwindcss/postcss": "^4.0.0",
+    "postcss": "^8.4.0",
+    "typescript": "^5.6.0"
+  }
+}

package/templates/stacks/ai-agent/scaffold/postcss.config.mjs

@@ -0,0 +1,7 @@
+const config = {
+  plugins: {
+    "@tailwindcss/postcss": {},
+  },
+};
+
+export default config;

package/templates/stacks/ai-agent/scaffold/supabase/migrations/0001_init.sql

@@ -0,0 +1,41 @@
+-- Initial migration. RLS on every table from the first migration.
+-- conversations + messages keyed to the auth user. Add pgvector tables in
+-- Phase 1 if the agent needs RAG.
+
+create table if not exists public.conversations (
+  id uuid primary key default gen_random_uuid(),
+  user_id uuid not null references auth.users (id) on delete cascade,
+  title text,
+  created_at timestamptz not null default now()
+);
+
+create table if not exists public.messages (
+  id uuid primary key default gen_random_uuid(),
+  conversation_id uuid not null references public.conversations (id) on delete cascade,
+  role text not null check (role in ('user', 'assistant', 'system')),
+  content text not null,
+  created_at timestamptz not null default now()
+);
+
+alter table public.conversations enable row level security;
+alter table public.messages enable row level security;
+
+create policy "conversations_own"
+  on public.conversations for all
+  using (auth.uid() = user_id)
+  with check (auth.uid() = user_id);
+
+create policy "messages_own"
+  on public.messages for all
+  using (
+    exists (
+      select 1 from public.conversations c
+      where c.id = messages.conversation_id and c.user_id = auth.uid()
+    )
+  )
+  with check (
+    exists (
+      select 1 from public.conversations c
+      where c.id = messages.conversation_id and c.user_id = auth.uid()
+    )
+  );

package/templates/stacks/ai-agent/scaffold/tsconfig.json

@@ -0,0 +1,21 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["dom", "dom.iterable", "ES2022"],
+    "allowJs": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "jsx": "preserve",
+    "incremental": true,
+    "plugins": [{ "name": "next" }],
+    "paths": { "@/*": ["./*"] }
+  },
+  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
+  "exclude": ["node_modules"]
+}

package/templates/stacks/ai-agent/stack.json

@@ -0,0 +1,9 @@
+{
+  "id": "ai-agent",
+  "title": "AI Agent",
+  "description": "LLM / chat / agent product — Supabase data + OpenRouter routing, optional Retell/ElevenLabs/Telnyx voice. Ships only when the eval suite is green.",
+  "archetype": "ai-agent",
+  "defaultStack": "Next.js 16 (Vercel) · Supabase (Postgres + pgvector) · OpenRouter · Tailwind · Railway (workers, optional)",
+  "scaffoldEntry": "app/api/chat/route.ts",
+  "whenToUse": "Chat, RAG, tool-using agents, or voice agents. Pick this when an LLM is the core of the product — it adds OpenRouter routing, eval gates, and cost guardrails on top of a full app."
+}

package/templates/stacks/ai-agent/verify-checklist.md

@@ -0,0 +1,31 @@
+# AI Agent — Definition of Done
+
+Per-stack verify checklist. Inherits `rules/constitution.md` and the `ai-agent` archetype DoD.
+
+## Foundation & data
+- [ ] Supabase with **RLS on every table** (conversations, messages, users, embeddings); pgvector if RAG.
+- [ ] Migrations in version control; RLS verified as two+ users.
+
+## Agent core
+- [ ] LLM via **OpenRouter** with model fallback — never a hardcoded single provider.
+- [ ] System prompts versioned in source, never inline.
+- [ ] Streaming responses; context-window management.
+
+## Evals (THE SHIP GATE)
+- [ ] Pass/fail eval suite over real cases — green before "done".
+- [ ] Covers the success metric AND the refusal/guardrail cases.
+
+## Guardrails & cost
+- [ ] Input validation; refusal/safety behavior; graceful fallback on model failure.
+- [ ] Per-request + daily cost ceilings; token + latency logging.
+- [ ] Each tool/action validated server-side; timeout + failure handling; idempotency on writes.
+
+## Voice (if applicable)
+- [ ] Latency budget < 800ms end-to-end through Retell + ElevenLabs + Telnyx.
+- [ ] End-to-end call testing pass/fail; turn-taking / barge-in verified.
+- [ ] Transcript logging + PII redaction; recording-consent disclosure.
+
+## Security & deploy
+- [ ] `service_role` server-only; OpenRouter/Retell/ElevenLabs/Telnyx keys in env, never logged.
+- [ ] `npx tsc --noEmit` exits 0; deploys to Vercel (+ Railway if worker).
+- [ ] Post-deploy smoke includes **real agent calls**.

package/templates/stacks/full-app/env.required.json

@@ -0,0 +1,20 @@
+[
+  {
+    "name": "NEXT_PUBLIC_SUPABASE_URL",
+    "purpose": "Supabase project URL — used by both client and server SDKs.",
+    "howToObtain": "Supabase Dashboard → Project Settings → API → Project URL, or `npx supabase projects list`.",
+    "ownerIssued": false
+  },
+  {
+    "name": "NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY",
+    "purpose": "Public (anon/publishable) key for client-side Supabase calls. Safe to expose; RLS protects data.",
+    "howToObtain": "Supabase Dashboard → Project Settings → API → Publishable/anon key.",
+    "ownerIssued": false
+  },
+  {
+    "name": "SUPABASE_SERVICE_ROLE_KEY",
+    "purpose": "Server-only service-role key for privileged mutations. NEVER prefixed NEXT_PUBLIC_, never imported into a client component.",
+    "howToObtain": "Supabase Dashboard → Project Settings → API → service_role key. Store server-side only.",
+    "ownerIssued": false
+  }
+]

package/templates/stacks/full-app/phases.md

@@ -0,0 +1,45 @@
+# Full App — Phase Plan
+
+Stack: Next.js 16 (App Router) · Supabase (auth + Postgres + RLS) · Tailwind · Vercel.
+Archetype: `web-app`. Seed plan copied into ROADMAP.md by `/qualia-new`.
+
+## Phase 1: Foundation, Auth & Data
+
+**Goal:** Stack deployed to a Vercel preview, Supabase wired with **RLS on every table from the first migration**, auth working end-to-end.
+
+**Success criteria:**
+1. User can sign up, log in, log out; session persists across refresh.
+2. Every table has RLS enabled with policies derived from `app_metadata` claims.
+3. RLS verified by logging in as two users — each sees only their own rows.
+4. Role-based routing enforced in middleware AND at the data layer.
+5. Deploys to a Vercel preview URL.
+
+## Phase 2: Core Capabilities (vertical slices)
+
+**Goal:** The primary user job works end-to-end — each capability cuts through UI + server action + RLS + validation + states.
+
+**Success criteria:**
+1. Primary user capability works end-to-end and persists.
+2. Every async surface has loading / empty / error states.
+3. Forms validate client AND server (Zod or equivalent); destructive actions confirm.
+4. Mutations go through `lib/supabase/server.ts`, never the client.
+
+## Phase 3: App Hardening
+
+**Goal:** Production-grade — rate limiting, audit/soft-delete, performance, security headers.
+
+**Success criteria:**
+1. Rate limiting on mutating + public endpoints.
+2. No N+1 on list views; perf budget met.
+3. `service_role` confirmed server-only; security headers (HSTS) set.
+4. Every UPDATE policy has a matching SELECT policy.
+
+## Phase 4: Polish & Handoff
+
+**Goal:** Design pass to anti-slop bar, a11y, prod deploy, credentials handover.
+
+**Success criteria:**
+1. DESIGN.md anti-slop bar met; a11y WCAG 2.2 AA.
+2. Analytics + Sentry; custom domain; production deploy + smoke.
+3. RLS / headers / env / MFA security pass.
+4. Credentials, walkthrough, archive, `/qualia-report` to ERP.

package/templates/stacks/full-app/scaffold/.env.example

@@ -0,0 +1,7 @@
+# Supabase — copy to .env.local and fill from your project.
+# `npx supabase projects list` or Dashboard → Project Settings → API.
+NEXT_PUBLIC_SUPABASE_URL=
+NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY=
+
+# Server-only. NEVER prefix with NEXT_PUBLIC_. Never import into a client component.
+SUPABASE_SERVICE_ROLE_KEY=

package/templates/stacks/full-app/scaffold/README.md

@@ -0,0 +1,28 @@
+# Full App
+
+Authenticated product — Next.js 16 + Supabase (auth + Postgres + RLS) + Tailwind + Vercel.
+
+## Run
+
+```bash
+npm install
+cp .env.example .env.local   # fill in Supabase keys
+npx supabase db push         # apply migrations (or link a project first)
+npm run dev                  # http://localhost:3000
+```
+
+## Where things live
+
+- `app/page.tsx` — entry; reads the session via the server adapter.
+- `lib/supabase/server.ts` — server adapter. **All mutations go here.**
+- `lib/supabase/client.ts` — browser adapter (publishable key only).
+- `supabase/migrations/` — schema. **Every table has RLS from the first migration.**
+- `.env.example` — required env. `SUPABASE_SERVICE_ROLE_KEY` is server-only.
+
+## Non-negotiables (constitution)
+
+- RLS on every table; authorize on `app_metadata`, never `user_metadata`.
+- `service_role` key never `NEXT_PUBLIC_`, never in a client component.
+- Schema changes are migrations only — never hand-applied to remote.
+
+This is an MVP skeleton. Build the real auth + capabilities per `.planning/ROADMAP.md`.

package/templates/stacks/full-app/scaffold/app/globals.css

@@ -0,0 +1,14 @@
+@import "tailwindcss";
+
+/* OKLCH design tokens. Source of truth is .planning/DESIGN.md.
+   NEVER raw #000 / #fff; tint neutrals toward the brand hue. */
+:root {
+  --brand: oklch(0.62 0.18 264);
+  --ink: oklch(0.21 0.01 264);
+  --paper: oklch(0.99 0.004 264);
+}
+
+body {
+  background: var(--paper);
+  color: var(--ink);
+}

package/templates/stacks/full-app/scaffold/app/layout.tsx

@@ -0,0 +1,19 @@
+import type { Metadata } from "next";
+import "./globals.css";
+
+export const metadata: Metadata = {
+  title: "Full App",
+  description: "Replace with your product's one-sentence pitch.",
+};
+
+export default function RootLayout({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  return (
+    <html lang="en">
+      <body>{children}</body>
+    </html>
+  );
+}

package/templates/stacks/full-app/scaffold/app/page.tsx

@@ -0,0 +1,20 @@
+import { createClient } from "@/lib/supabase/server";
+
+export default async function Home() {
+  // Server Component reading the session through the RLS-aware adapter.
+  const supabase = await createClient();
+  const {
+    data: { user },
+  } = await supabase.auth.getUser();
+
+  return (
+    <main className="mx-auto flex min-h-dvh max-w-3xl flex-col justify-center gap-6 px-6">
+      <h1 className="text-4xl font-semibold tracking-tight">Full App</h1>
+      <p className="text-lg text-neutral-600">
+        {user
+          ? `Signed in as ${user.email}.`
+          : "Not signed in. Wire the auth flow in Phase 1, then build your core capability."}
+      </p>
+    </main>
+  );
+}

package/templates/stacks/full-app/scaffold/lib/supabase/client.ts

@@ -0,0 +1,10 @@
+import { createBrowserClient } from "@supabase/ssr";
+
+// Client-side Supabase adapter. Uses the publishable (anon) key only.
+// NEVER import the service-role key here — RLS protects the data.
+export function createClient() {
+  return createBrowserClient(
+    process.env.NEXT_PUBLIC_SUPABASE_URL!,
+    process.env.NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY!
+  );
+}

package/templates/stacks/full-app/scaffold/lib/supabase/server.ts

@@ -0,0 +1,31 @@
+import { createServerClient } from "@supabase/ssr";
+import { cookies } from "next/headers";
+
+// Server-side Supabase adapter. Use this for all mutations and any
+// RLS-protected read that needs the caller's session. The only seam that
+// touches @supabase/ssr on the server.
+export async function createClient() {
+  const cookieStore = await cookies();
+
+  return createServerClient(
+    process.env.NEXT_PUBLIC_SUPABASE_URL!,
+    process.env.NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY!,
+    {
+      cookies: {
+        getAll() {
+          return cookieStore.getAll();
+        },
+        setAll(cookiesToSet) {
+          try {
+            cookiesToSet.forEach(({ name, value, options }) =>
+              cookieStore.set(name, value, options)
+            );
+          } catch {
+            // Called from a Server Component — safe to ignore when middleware
+            // refreshes the session.
+          }
+        },
+      },
+    }
+  );
+}

package/templates/stacks/full-app/scaffold/next.config.mjs

@@ -0,0 +1,7 @@
+/** @type {import('next').NextConfig} */
+const nextConfig = {
+  // App routes are server-rendered (Supabase session). Add `noindex` headers
+  // on the app shell in Phase 4 — SEO belongs on public routes only.
+};
+
+export default nextConfig;

package/templates/stacks/full-app/scaffold/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "full-app",
+  "version": "0.1.0",
+  "private": true,
+  "scripts": {
+    "dev": "next dev",
+    "build": "next build",
+    "start": "next start",
+    "lint": "next lint",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "next": "^16.0.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "@supabase/supabase-js": "^2.45.0",
+    "@supabase/ssr": "^0.5.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "tailwindcss": "^4.0.0",
+    "@tailwindcss/postcss": "^4.0.0",
+    "postcss": "^8.4.0",
+    "typescript": "^5.6.0"
+  }
+}

package/templates/stacks/full-app/scaffold/postcss.config.mjs

@@ -0,0 +1,7 @@
+const config = {
+  plugins: {
+    "@tailwindcss/postcss": {},
+  },
+};
+
+export default config;

package/templates/stacks/full-app/scaffold/supabase/migrations/0001_init.sql

@@ -0,0 +1,27 @@
+-- Initial migration. RLS is enabled FROM THE FIRST MIGRATION, not retrofitted.
+-- Replace `profiles` with your real domain tables — keep the RLS pattern.
+
+create table if not exists public.profiles (
+  id uuid primary key references auth.users (id) on delete cascade,
+  display_name text,
+  created_at timestamptz not null default now()
+);
+
+-- RLS on every table (constitution).
+alter table public.profiles enable row level security;
+
+-- A user may read their own row.
+create policy "profiles_select_own"
+  on public.profiles for select
+  using (auth.uid() = id);
+
+-- A user may update their own row. (Every UPDATE policy has a matching SELECT.)
+create policy "profiles_update_own"
+  on public.profiles for update
+  using (auth.uid() = id)
+  with check (auth.uid() = id);
+
+-- A user may insert their own row.
+create policy "profiles_insert_own"
+  on public.profiles for insert
+  with check (auth.uid() = id);

package/templates/stacks/full-app/scaffold/tsconfig.json

@@ -0,0 +1,21 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["dom", "dom.iterable", "ES2022"],
+    "allowJs": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "jsx": "preserve",
+    "incremental": true,
+    "plugins": [{ "name": "next" }],
+    "paths": { "@/*": ["./*"] }
+  },
+  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
+  "exclude": ["node_modules"]
+}

package/templates/stacks/full-app/stack.json

@@ -0,0 +1,9 @@
+{
+  "id": "full-app",
+  "title": "Full App",
+  "description": "Authenticated product — Supabase auth + Postgres + RLS, Tailwind UI, deployed on Vercel. The default for anything with user accounts and persisted data.",
+  "archetype": "web-app",
+  "defaultStack": "Next.js 16 (App Router) · Supabase (auth + Postgres + RLS) · Tailwind · Vercel",
+  "scaffoldEntry": "app/page.tsx",
+  "whenToUse": "Any product with logged-in users, roles, and a database. Pick this when users sign up, data persists per-user, and RLS must isolate tenants."
+}

package/templates/stacks/full-app/verify-checklist.md

@@ -0,0 +1,32 @@
+# Full App — Definition of Done
+
+Per-stack verify checklist. Inherits `rules/constitution.md` and the `web-app` archetype DoD.
+
+## Auth & Access (constitution — non-negotiable)
+- [ ] Supabase auth with the chosen model; email verification + password reset wired.
+- [ ] **RLS enabled on every table**, policies derived from `app_metadata` (never `user_metadata`).
+- [ ] RLS verified as two+ users — each sees only its own rows.
+- [ ] Every UPDATE policy has a matching SELECT policy.
+- [ ] Postgres views set `security_invoker = true`.
+- [ ] Storage upsert grants INSERT + SELECT + UPDATE on the bucket.
+- [ ] Sessions revoked before a user is deleted.
+
+## Security
+- [ ] `SUPABASE_SERVICE_ROLE_KEY` is server-only — never `NEXT_PUBLIC_`, never imported in a client component.
+- [ ] Mutations use `lib/supabase/server.ts`; client reads use `lib/supabase/client.ts`.
+- [ ] Inputs validated with Zod; no `dangerouslySetInnerHTML`, no `eval()`.
+- [ ] Security headers (HSTS); CSRF/permission checks on every mutation.
+
+## Schema flow
+- [ ] All schema changes are migrations in `supabase/migrations/` — never hand-applied to remote.
+- [ ] `npx supabase gen types` run after schema changes.
+
+## App quality
+- [ ] Every async surface has loading / empty / error states.
+- [ ] Destructive actions confirm; rate limiting on mutating + public endpoints.
+- [ ] No N+1 on list views.
+
+## Build & Deploy
+- [ ] `npx tsc --noEmit` exits 0; `next build` succeeds.
+- [ ] Deploys to Vercel; homepage returns HTTP 200; auth callback responds.
+- [ ] Design anti-slop bar met (DESIGN.md); a11y AA.

package/templates/stacks/internal-tool/env.required.json

@@ -0,0 +1,20 @@
+[
+  {
+    "name": "NEXT_PUBLIC_SUPABASE_URL",
+    "purpose": "Supabase project URL — used by both client and server SDKs.",
+    "howToObtain": "Supabase Dashboard → Project Settings → API → Project URL, or `npx supabase projects list`.",
+    "ownerIssued": false
+  },
+  {
+    "name": "NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY",
+    "purpose": "Public (anon/publishable) key for client-side Supabase calls. RLS protects data.",
+    "howToObtain": "Supabase Dashboard → Project Settings → API → Publishable/anon key.",
+    "ownerIssued": false
+  },
+  {
+    "name": "SUPABASE_SERVICE_ROLE_KEY",
+    "purpose": "Server-only service-role key — also used to invite staff users from a server action. NEVER NEXT_PUBLIC_, never in a client component.",
+    "howToObtain": "Supabase Dashboard → Project Settings → API → service_role key.",
+    "ownerIssued": false
+  }
+]

package/templates/stacks/internal-tool/phases.md

@@ -0,0 +1,45 @@
+# Internal Tool — Phase Plan
+
+Stack: Next.js 16 (App Router) · Supabase (portal auth + RLS) · Tailwind · Vercel.
+Archetype: `web-app` (internal/living product — runs as a rolling release, no terminal Handoff).
+Seed plan copied into ROADMAP.md by `/qualia-new`.
+
+## Phase 1: Foundation, Portal Auth & Roles
+
+**Goal:** Stack on a Vercel preview; Supabase wired with RLS on every table; invite-only auth (no public signup); roles in `app_metadata`.
+
+**Success criteria:**
+1. Staff log in (invite / SSO); public signup is disabled.
+2. Roles stored in `app_metadata`; role-based routing in middleware AND data layer.
+3. Every table has RLS; verified as two roles — each sees only its scope.
+4. Deploys to a Vercel preview URL.
+
+## Phase 2: Core Workflows (vertical slices)
+
+**Goal:** The primary staff workflows work end-to-end — list, detail, create/edit, with states.
+
+**Success criteria:**
+1. Primary workflow works end-to-end and persists.
+2. Every async surface has loading / empty / error states.
+3. Forms validate client AND server; destructive actions confirm + soft-delete where flagged.
+4. Mutations go through `lib/supabase/server.ts`.
+
+## Phase 3: Admin, Audit & Hardening
+
+**Goal:** User management, audit trail, rate limiting, performance.
+
+**Success criteria:**
+1. Admin can invite / deactivate users and assign roles.
+2. Audit log on sensitive writes; soft-delete where flagged.
+3. No N+1 on list views; rate limiting on mutating endpoints.
+4. Every UPDATE policy has a matching SELECT policy.
+
+## Phase 4: Polish & Rolling Release
+
+**Goal:** Design pass, a11y, prod deploy. As a living product this repeats per increment — no terminal Handoff.
+
+**Success criteria:**
+1. DESIGN.md anti-slop bar; a11y WCAG 2.2 AA.
+2. `service_role` server-only; security headers; MFA on accounts.
+3. Production deploy + smoke (HTTP 200, auth callback, role isolation).
+4. `/qualia-report` per increment.

package/templates/stacks/internal-tool/scaffold/.env.example

@@ -0,0 +1,7 @@
+# Supabase — internal portal. Public signup disabled; staff join by invite.
+NEXT_PUBLIC_SUPABASE_URL=
+NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY=
+
+# Server-only — also used to invite staff from a server action.
+# NEVER prefix with NEXT_PUBLIC_, never import into a client component.
+SUPABASE_SERVICE_ROLE_KEY=

package/templates/stacks/internal-tool/scaffold/README.md

@@ -0,0 +1,29 @@
+# Internal Tool
+
+Staff-facing portal — Next.js 16 + Supabase (invite-only auth + RLS) + Tailwind + Vercel.
+Public signup is disabled; staff join by invite / SSO. Runs as a rolling release.
+
+## Run
+
+```bash
+npm install
+cp .env.example .env.local   # fill Supabase keys
+npx supabase db push
+npm run dev                  # http://localhost:3000
+```
+
+## Where things live
+
+- `app/page.tsx` — portal entry; reads session + role from `app_metadata`.
+- `lib/supabase/server.ts` — server adapter (mutations, RLS, inviting staff).
+- `lib/supabase/client.ts` — browser adapter (publishable key only).
+- `supabase/migrations/` — domain tables, RLS + role gating from the first migration.
+
+## Non-negotiables (constitution)
+
+- Roles live in `app_metadata`, never `user_metadata`.
+- RLS on every table; every UPDATE policy has a matching SELECT.
+- `service_role` server-only; used for inviting users from a server action.
+- Disable public signup in the Supabase Auth settings.
+
+This is an MVP skeleton. Build portal auth + workflows per `.planning/ROADMAP.md`.

package/templates/stacks/internal-tool/scaffold/app/globals.css

@@ -0,0 +1,13 @@
+@import "tailwindcss";
+
+/* OKLCH design tokens. Source of truth is .planning/DESIGN.md. */
+:root {
+  --brand: oklch(0.62 0.18 264);
+  --ink: oklch(0.21 0.01 264);
+  --paper: oklch(0.99 0.004 264);
+}
+
+body {
+  background: var(--paper);
+  color: var(--ink);
+}