/iblai-vibe-scaffold

Mirrored from iblai/vibe · skills/start/iblai-vibe-scaffold/SKILL.md. This page is generated — edit it in the repository, not here.

First time here? If iblai.env has no ARCHITECTURE=, run /iblai-vibe-start first (four questions; two minutes) — it decides single-org / multi-org / headless and who signs in, and every skill reads the answer.

How an ibl.ai app gets its skeleton: the project templates that scaffold a new app or add a feature, and the steps that assemble them. The templates here record what a generated app contains; the references document the assembly steps so the skills can perform them directly — copy the assets/ files, then apply the patches described in each reference.

Do NOT add custom styles / colors to ibl.ai SDK components — they ship with their own styling. See BRAND.md.

Common setup (env, conventions, verification): see docs/skill-setup.md.

Two ways in

Both map PLATFORM/TOKEN/DOMAIN from iblai.env into the NEXT_PUBLIC_* vars in .env.local (see references/config-command.md).

Prefer the starter for greenfield work. For brand-new projects, vibe-starter (the pre-wired template bundled with /iblai-vibe-ops-init — see the repo CLAUDE.md "Getting Started") is the recommended path; the base+agent templates here are the manual equivalent.

Env: .env.local before build

A vibe app (scaffolded from vibe-starter or copied from these templates) reads its config from .env.local. Always ensure one exists before pnpm build — a missing file is the usual cause of a mis-tenanted build. (vibe-starter apps carry the URL defaults in code, so only the organization key and IBLAI_API_KEY are at stake; apps copied from these templates carry the full set in .env.example):

[ -f .env.local ] || cp .env.example .env.local

No .env.example in the project? Seed one from assets/base/.env.example. Then map PLATFORM → NEXT_PUBLIC_MAIN_TENANT_KEY and TOKEN → IBLAI_API_KEY from iblai.env (see references/config-command.md).

The templates

The templates are real files under assets/, named as they land in the app; nothing to render. Two literal defaults are what an agent renames — the package name my-app (package.json) and the title My App (app/layout.tsx); everything per organization is read from .env.local at runtime (NEXT_PUBLIC_MAIN_TENANT_KEY, NEXT_PUBLIC_DEFAULT_AGENT_ID, …).

• assets/base/ — the foundation: app/(app)/{layout,page}.tsx (a welcome home page), providers/index.tsx, store/index.ts, lib/iblai/{auth-utils,config}.ts, lib/config.ts, next.config.ts, components/ui/{button,sonner}.tsx, package.json, .env.example.
• assets/shared/ — in every app: root app/layout.tsx, the (auth)/sso-login-complete callback, components/app-shell.tsx, providers/store-provider.tsx, hooks/use-user.ts, lib/{utils,hooks}.ts, AGENTS.md (copy or symlink it to CLAUDE.md), the MCP servers for Claude Code (.mcp.json + the .claude/settings.json that pre-approves them), Cursor (.cursor/mcp.json), Codex (.codex/config.toml) and opencode (opencode.json), public/env.js, the tooling configs (eslint/tsconfig/tailwind/postcss/vitest), and the Playwright e2e/ suite.
• assets/agent/ — the agent app's two files on top: the chat home page app/(app)/page.tsx (full-screen ChatWidget) and its e2e/journeys/chat.journey.spec.ts.

Assemble an app in this order (the /. form keeps the dotfiles):

cp -R assets/base/. my-app/ && cp -R assets/shared/. my-app/
cp -R assets/agent/. my-app/              # agent app only
cd my-app && cp .env.example .env.local   # then set the org key, token and agent id
pnpm install --ignore-scripts

The Tauri desktop/mobile shell (src-tauri/, CI workflows) lives with the build skill: iblai-vibe-ops-build/assets/tauri/.

Per-feature templates (auth, account, analytics, chat, notification, profile) live with their skill's assets, not here — e.g. iblai-vibe-auth/assets/, iblai-vibe-account/assets/. Icons live in iblai-vibe-ops-build/assets/icons/.

Feature skills

Each feature has its own skill that copies its assets and applies its patches: /iblai-vibe-auth (SSO, store, providers — run first), then /iblai-vibe-agent-chat, /iblai-vibe-profile, /iblai-vibe-account, /iblai-vibe-analytics, /iblai-vibe-notification, /iblai-vibe-ops-build, and the rest of the /iblai-vibe-* family.

Provider chain (what base wires up)

AuthProvider > TenantProvider > {children}

initializeDataLayer(dmUrl, lmsUrl, legacyLmsUrl, storageService, httpErrorHandler) is called with 5 args (data-layer v1.2+). Redux Toolkit is deduplicated via a webpack resolve.alias in next.config.ts — without it, SDK components bind a different ReactReduxContext and RTK Query hooks return undefined. The base templates encode all of this; reproduce them faithfully if scaffolding by hand.

References

• references/add-command.md — adding a feature by hand — the copy→patch contract.
• references/config-command.md — .env.local reference — known variables and defaults.

Related skills

• /iblai-vibe-auth — SSO auth, store, providers (run first).
• /iblai-vibe-ops-build — Tauri desktop/mobile shell.
• /iblai-vibe-ops-deploy — deploy to Vercel.
• /iblai-vibe-ops-init — update a project's CLAUDE.md with platform guidance.