Initialize Your Project

After create-red-app scaffolds the codebase, run /red-init once to turn the starter into your project. It is an interactive setup skill: it asks questions, shows a summary, waits for your confirmation, then applies the changes.

Prerequisites

• Open Claude Code in the RED project root.
• The project was scaffolded with bun create red-app my-project --license <key>.
• .red-version exists and is committed.
• .red-license exists and is git-ignored.

If .red-version or .red-license is missing, the skill stops and asks you to scaffold with create-red-app first.

Run the Skill

/red-init

The skill follows a fixed sequence so setup stays reviewable.

Phase 0: Preflight

The skill verifies:

• .red-license exists.
• .red-version exists.
• .gitignore ignores .red-license.
• .red-version remains tracked because future updates use it as the RED base version.

Phase 0b: Convex Backend

RED uses Convex for backend functions, storage, scheduling, and reactive data. The skill asks how you want to configure it:

• Existing project — provide a deployment name like my-app-123. The skill writes .env.local with CONVEX_DEPLOYMENT, VITE_CONVEX_URL, and VITE_CONVEX_SITE_URL.
• Create a new project — run bunx convex dev --once in a separate terminal. The Convex CLI needs browser login and project selection, so the skill waits for you to confirm when it completes.
• Skip for now — continue setup and configure Convex later.

After Convex setup, the skill checks .env.local. If the Convex CLI wrote CONVEX_URL or CONVEX_SITE_URL, the skill renames them to VITE_CONVEX_URL and VITE_CONVEX_SITE_URL because Vite only exposes VITE_ variables to the frontend.

Phase 0c: Deployment Auth Environment Variables

When Convex is configured (Options A or B above), the skill bootstraps auth-related deployment env vars before seeding the admin user:

1. BETTER_AUTH_SECRET — a freshly generated secret for Better Auth session and cookie signing. Without it, sign-in and bun run seed fail.
2. SITE_URL — the browser origin your app runs on (default http://localhost:5173 for local Vite dev). This drives CORS on auth routes, trustedOrigins, and email links until you set Site URL in Admin > Configure > General.

If you skip Convex setup, the skill lists the exact npx convex env set commands in the completion message so you can run them after bunx convex dev --once.

Private key material is never written to the repo, local env files, or the wizard output.

Phase 1: Project Name

Choose the name shown in the app, emails, and admin UI.

Phase 2: Domain Path

RED ships with an integrated Briefs + AI reference application. Choose one:

• Keep RED as-is — the Briefs + AI app stays intact as a working reference.
• Make it yours — replace the Briefs surface with your own first-class entity and dashboard while keeping the AI engine, workspaces, and tasks as infrastructure.

For a custom entity, the skill asks for entity name and purpose, key fields, an optional child entity, and whether the AI assistant should act on the new entity.

Phase 3: Auth and Access

Choose:

• Signup mode — open signup, waitlist first, or invite only.
• Organization creation — users can create organizations, or only admins can create them.

These choices update the default configuration used by the app and admin settings.

Phase 4: Optional Peripheral Modules

Choose which optional modules to keep:

• Billing — Autumn plans, entitlements, metered usage, and Stripe checkout.
• API Keys — org-scoped API keys with JWT token exchange at /api/v1/auth/token and rate limiting.

Core platform modules (auth, AI, workspaces, tasks, and others) always stay. Modules you remove are deleted from code and integration points are cleaned up.

Phase 4c: API Keys JWT Keys

If you keep API Keys and Convex is configured, the skill generates an ES256 P-256 keypair and sets APIKEY_JWT_PRIVATE_KEY and APIKEY_JWT_PUBLIC_KEY on the deployment. These power token exchange and the /.well-known/jwks.json endpoint used by Convex customJwt validation.

If you remove API Keys or skipped Convex setup, this step is skipped (deferred commands appear in the completion message when applicable).

Phase 4b: Documentation Site

RED includes apps/docs/, which documents RED itself. Most product teams remove it during initialization. Keep it only if you want to repurpose it as your own docs site.

Phase 5: Summary and Confirmation

The skill shows a summary of every choice, including which deployment env vars were set or deferred. No files are changed until you confirm.

Phase 6: Apply Changes

After confirmation, the skill applies changes in order:

1. Updates the project name in configuration.
2. Keeps or replaces the domain path (Briefs surface).
3. Applies auth and organization defaults.
4. Removes unselected optional modules.
5. Removes apps/docs/ if requested.
6. Runs bun run lint and bunx convex dev --once when Convex is configured.
7. Runs bun run seed if Convex is configured (requires Phase 0c env vars).
8. Removes starter-kit seed scripts.

If Convex was skipped, backend seeding and seed-script removal are deferred.

Phase 7: Verify

When Convex is configured, the skill:

1. Derives the Convex HTTP base URL from .env.local.
2. If API Keys was kept, curls /.well-known/jwks.json (expects kid: apikey-v1, alg: ES256) to confirm the public key is set, and POST /api/v1/auth/token with a bogus key (expects 401) to confirm the route is live. The bogus-key call can’t verify the signing keys — an invalid key is rejected with 401 before the misconfiguration check runs — so end-to-end signing is confirmed by exchanging a real key after seeding.

After Initialization

Run the app:

bun dev

If Convex was skipped, configure it first:

bunx convex dev --once
npx convex env set BETTER_AUTH_SECRET "$(openssl rand -base64 32)"
npx convex env set SITE_URL "http://localhost:5173"
(
  set -e
  tmpdir="$(mktemp -d)"
  trap 'rm -rf "$tmpdir"' EXIT
  openssl ecparam -name prime256v1 -genkey -noout | openssl pkcs8 -topk8 -nocrypt -out "$tmpdir/sk.pem"
  openssl ec -in "$tmpdir/sk.pem" -pubout -out "$tmpdir/pk.pem"
  npx convex env set APIKEY_JWT_PRIVATE_KEY -- "$(cat "$tmpdir/sk.pem")"
  npx convex env set APIKEY_JWT_PUBLIC_KEY -- "$(cat "$tmpdir/pk.pem")"
)
bun run seed

Then open http://localhost:5173, sign in with the seeded admin credentials, and verify the app loads with no console errors.

Important Notes

• Treat /red-init as first-time setup for a freshly scaffolded project.
• Do not delete core platform modules: auth, admin, audit, config, email, users, organizations, AI, workspaces, or tasks.
• Set RESEND_API_KEY in Convex environment variables before relying on real email delivery.
• For production, update SITE_URL in the Convex env (or Site URL in Admin > Configure > General) to your production origin.