Iblai Vibe Ops Init

---
name: iblai-vibe-ops-init
description: Start a new ibl.ai project by default, scaffold from the bundled vibe-starter template, and write the project CLAUDE.md with ibl.ai platform guidance. Use this when the user says "start a new project", "new app", "scaffold an app", "new ibl.ai project", or asks to bootstrap an ibl.ai codebase from scratch. Also use to refresh CLAUDE.md in an existing ibl.ai project.
globs:
alwaysApply: false
---

# /iblai-vibe-ops-init

Bootstrap a new ibl.ai project (defaults to scaffolding from the bundled
vibe-starter template) and write
or update the project's `CLAUDE.md` with ibl.ai platform guidance. The
CLAUDE.md tells Claude Code how to work with the project -- which components
to use, how to add features, and what patterns to follow.

## What This Skill Does

1. **If the working directory is empty / a brand-new project:** scaffold
   from the bundled vibe-starter (Step 0) before doing anything else
2. Check if `CLAUDE.md` already exists in the project root
3. If it exists, **merge** the ibl.ai section into it (do not overwrite
   existing content)
4. If it does not exist, **create** it with the full ibl.ai guidance below

## Step 0: Offer vibe-starter (new projects)

If the user is starting a new project from scratch (empty directory, no
`package.json`, or they said "new project" / "scaffold" / "new app"),
**ask whether they want to use vibe-starter** -- a pre-wired Next.js 16 +
Tailwind v4 + shadcn/ui template with ibl.ai SSO auth, a responsive navbar,
and profile/account/notifications pages already in place.

### Check the opt-out flag first

Before asking, check `iblai.env` for `USE_VIBE_STARTER`:

```bash
[ -f iblai.env ] && grep -E '^USE_VIBE_STARTER=' iblai.env
```

- If `iblai.env` exists **and** `USE_VIBE_STARTER` is set to a falsy value
  (`false`, `0`, `no`, `off`, empty), **skip vibe-starter and skip the
  question entirely** -- go straight to Step 1 to write CLAUDE.md, then
  resume whatever the user originally asked for. Do NOT scaffold a vanilla
  Next.js app.
- Otherwise, ask the user.

### Ask the user

Ask a clear yes/no question:

> Want to scaffold from **vibe-starter**? It's a pre-wired Next.js 16 +
> Tailwind v4 + shadcn/ui template with ibl.ai SSO auth, a responsive
> navbar, and profile/account/notifications pages already wired up.

- **If they say yes / use it / vibe-starter:** materialize the starter (below).
- **If they say no / skip:** go straight to Step 1 to write CLAUDE.md,
  then resume whatever the user originally asked for. Do NOT scaffold a
  vanilla Next.js app -- the user said skip.

### Materialize the starter (only if the user said yes)

The starter template ships with this skill, in the `assets/vibe-starter/`
directory beside this SKILL.md. Copy it into the project root (`cp -a`
keeps the dotfiles), then install:

```bash
cp -a <this-skill-dir>/assets/vibe-starter/. .
pnpm install --ignore-scripts
git init   # only if the project is not already a git repo
```

> Run with `--ignore-scripts` to skip package lifecycle (postinstall) scripts.

If this skill was installed without its `assets/` directory (some
installers ship only the SKILL.md), fetch the template from the vibe repo
instead -- tell the user that is the path you are taking:

```bash
git clone --depth 1 https://github.com/iblai/vibe.git vibe-tmp
cp -a vibe-tmp/skills/iblai-vibe-ops-init/assets/vibe-starter/. . && rm -rf vibe-tmp
pnpm install --ignore-scripts
git init   # only if the project is not already a git repo
```

### Resolve platform credentials and write env files

After the copy completes, climb this ladder and stop at the first rung that
yields both values. Inside the ibl.ai desktop app both rungs 1 and 2 hit, so
the user is asked nothing:

1. **`iblai.env` already exists with real values for both `PLATFORM` and
   `TOKEN`** -- reuse them and skip the prompts entirely.

2. **Otherwise read them from the environment.** The ibl.ai desktop app
   exports `IBLAI_API_KEY`, `IBLAI_PLATFORM_KEY`, and `IBLAI_USERNAME` into
   the agent's environment. Use whatever is present without asking for it and
   without echoing it back:

   ```bash
   PLATFORM="${IBLAI_PLATFORM_KEY:-}"
   TOKEN="${IBLAI_API_KEY:-}"
   ```

   When `IBLAI_USERNAME` is exported, persist it to `iblai.env` as well --
   that saves `/iblai-vibe-ops-deploy` asking for it later.

3. **Ask only for the values still missing** -- standalone opencode / Claude
   Code users outside the desktop app:

   > What is your ibl.ai **PLATFORM** (tenant key)?

   > What is your ibl.ai **TOKEN** (platform API key)?

   Never ask for `TOKEN` when `IBLAI_API_KEY` is exported -- the environment
   already answered it.

Then write the values to both files:

1. **`iblai.env`** -- create if missing, or update the `PLATFORM` and `TOKEN`
   lines in place. `DOMAIN` is the platform's **base domain**: inside the
   ibl.ai desktop app your session guidance states it ("The platform's base
   domain is …") -- write exactly that value, and if an existing `iblai.env`
   disagrees with it, update `DOMAIN` to match (a stale domain sends every
   skill to the wrong host). Outside the desktop app keep whatever the user
   already set, defaulting to `iblai.app`. Example contents:

   ```
   DOMAIN=iblai.app
   PLATFORM=<the value the user gave>
   TOKEN=<the value the user gave>
   ```

2. **`.env.local`** -- write directly. Do NOT re-run any scaffolding (e.g.
   the `/iblai-vibe-auth` file generation) -- the starter already has everything
   wired and regenerating those files can clobber the starter's versions.
   If `.env.local` does not exist yet, copy the starter's example first
   (`cp .env.example .env.local`), then update or append both lines (write
   `TOKEN` as `IBLAI_API_KEY`). The API/auth/websocket URLs default to
   hosted iblai.app in `lib/iblai/config.ts`, so when `DOMAIN` is
   `iblai.app` these two values are all that must change:

   ```
   NEXT_PUBLIC_MAIN_TENANT_KEY=<PLATFORM>
   IBLAI_API_KEY=<TOKEN>
   ```

   When `DOMAIN` is anything else, the hosted defaults would point at the
   wrong platform -- also write, from the same `DOMAIN` (and the sign-in URL
   your session guidance states, if it states one; the auth host is NOT
   derivable from the domain, so never guess it):

   ```
   NEXT_PUBLIC_PLATFORM_BASE_DOMAIN=<DOMAIN>
   NEXT_PUBLIC_API_BASE_URL=https://api.<DOMAIN>
   NEXT_PUBLIC_AUTH_URL=<the sign-in URL from the session guidance, when given>
   ```

Do NOT print or echo the `TOKEN` / `IBLAI_API_KEY` value back to the user
once captured.

`IBLAI_API_KEY` also unlocks LLM features without any separate provider key:
it is a standard OpenAI api key on the platform's OpenAI-compatible endpoint.
Point any OpenAI client at
`base_url = https://asgi.data.{DOMAIN}/api/ai-mentor/orgs/{PLATFORM}/v1` with
the key as `api_key` (sent as `Authorization: Bearer …`) for chat completions
(including streaming) and model listing (`GET /models` returns what the
platform can actually serve). Server-side only, like every other use of the
key — never in client code. Note the `Bearer` scheme applies to this `/v1`
surface only; all other platform APIs keep `Authorization: Api-Token`.

After the starter is in place, the user's project already has auth, navbar,
profile, account, and notifications wired. They can skip the matching
`/iblai-vibe-auth`, `/iblai-vibe-navbar`, `/iblai-vibe-profile`, `/iblai-vibe-account`, and
`/iblai-vibe-notification` skills.

**Skip the offer entirely if:**
- `iblai.env` has `USE_VIBE_STARTER` set to a falsy value (see above)
- The directory already has a `package.json` (existing project) -- in
  that case go straight to Step 1

## Step 1: Check for Existing CLAUDE.md

Read `CLAUDE.md` in the current working directory. If it exists, append the
ibl.ai section below (under a `## ibl.ai Platform` heading) without
duplicating content that's already there. If there's already an ibl.ai
section, replace it with the updated version below.

## Step 2: Write the CLAUDE.md Content

The CLAUDE.md should contain the following content. Adapt the heading level
if merging into an existing file (e.g., use `##` if appending to a file
that already has a top-level `#` heading).

---

### Content to write

```markdown
# CLAUDE.md

This project is built on the ibl.ai platform using the `@iblai/iblai-js` SDK.

## Starter Template

When the user says "start a new project", "new app", "scaffold an app", or
anything that creates a fresh codebase, run the `/iblai-vibe-ops-init` skill --
it scaffolds from the bundled vibe-starter template (a pre-wired Next.js 16 +
Tailwind v4 + shadcn/ui app with ibl.ai SSO auth, a responsive navbar, and
profile/account/notifications pages already in place), skipping the manual
`/iblai-vibe-auth`, `/iblai-vibe-navbar`, `/iblai-vibe-profile`, `/iblai-vibe-account`,
and `/iblai-vibe-notification` skills. Only fall back to a vanilla Next.js app
wired up via the individual `/iblai-vibe-*` skills if the user explicitly
declines the starter or asks for a minimal/custom setup.

For existing projects, ignore this and use the individual skills below.

## Component Priority

When adding UI features, follow this priority order:

1. **ibl.ai components** (`@iblai/iblai-js`) -- always use these first
2. **shadcn/ui** (`npx shadcn@latest add`) -- for everything else
3. **Custom/third-party** -- only when no ibl.ai or shadcn component exists

### When the user asks to add...

| Feature | Use this | NOT this |
|---------|----------|----------|
| Profile page / dropdown | `/iblai-vibe-profile` skill + `Profile`, `UserProfileDropdown` from SDK | Custom profile form |
| Account / org settings | `/iblai-vibe-account` skill + `Account` from SDK | Custom settings page |
| Analytics dashboard | `/iblai-vibe-analytics` skill + `AnalyticsOverview`, `AnalyticsLayout` from SDK | Chart library from scratch |
| Notifications | `/iblai-vibe-notification` skill + `NotificationDropdown` from SDK | Custom notification system |
| Chat / AI assistant | `/iblai-vibe-agent-chat` skill + `Chat` from SDK | Custom chat UI |
| Auth / login | `/iblai-vibe-auth` skill + `AuthProvider`, `SsoLogin` from SDK | Custom auth flow |
| Invite users | `/iblai-vibe-invite` skill + `InviteUserDialog` from SDK | Custom invite form |
| Workflow builder | `/iblai-vibe-workflow` skill + workflow components from SDK | Custom node editor |
| Course content | `/iblai-vibe-course-access` skill + `CourseContentLayout`, `CourseContentTabPage` from SDK | Custom course player |
| Create / publish courses | `/iblai-vibe-course-create` skill (Course Creation API) | Manually authoring OLX in edX Studio |
| Onboarding flow | `/iblai-vibe-onboard` skill | Custom onboarding from scratch |
| Buttons, forms, modals, tables | shadcn/ui (`npx shadcn@latest add button dialog table`) | Raw HTML or other UI libraries |
| Page sections / blocks | shadcn/ui blocks (`npx shadcn@latest add @shadcn-space/hero-01`) | Custom layout from scratch |

### Key rule

Do NOT build custom components when an ibl.ai SDK component exists.
Do NOT use raw HTML or third-party UI libraries when shadcn/ui has an equivalent.
ibl.ai and shadcn share the same Tailwind theme -- they render in brand colors automatically.

## SDK Imports

```typescript
// Data layer
import { initializeDataLayer, mentorReducer } from "@iblai/iblai-js/data-layer";

// Auth & utilities
import { AuthProvider, TenantProvider, useChatV2 } from "@iblai/iblai-js/web-utils";

// Framework-agnostic components
import { Profile, AnalyticsLayout, NotificationDropdown } from "@iblai/iblai-js/web-containers";

// Next.js-specific components
import { SsoLogin, UserProfileDropdown, Account } from "@iblai/iblai-js/web-containers/next";
```

## Adding Features

Use skills to add features. Each skill creates the files and guides you
through the wiring:

```
/iblai-vibe-auth          # SSO authentication (run first)
/iblai-vibe-agent-chat    # In-process agent chat surface
/iblai-vibe-profile       # Profile dropdown + settings page
/iblai-vibe-account       # Account/org settings page
/iblai-vibe-analytics     # Analytics dashboard
/iblai-vibe-course-access # Course content pages (edX user UI)
/iblai-vibe-course-create # Generate and publish courses via Course Creation API
/iblai-vibe-notification  # Notification bell
/iblai-vibe-invite        # User invitation dialogs
/iblai-vibe-workflow      # Workflow builder
/iblai-vibe-onboard       # Onboarding questionnaire flow
/iblai-vibe-ops-build     # Desktop/mobile builds (Tauri v2)
/iblai-vibe-ops-test      # Test before showing work
/iblai-vibe-ops-upgrade   # Upgrade SDK and skills to latest
/iblai-vibe-component     # Browse all available components
```

All features require auth first (`/iblai-vibe-auth`).

## Environment

Platform configuration lives in `iblai.env` (`DOMAIN`, `PLATFORM`, `TOKEN`,
and optionally `IBLAI_USERNAME` — your platform username; the
`IBLAI_USERNAME` environment variable wins when the host exports it, and the
deploy skill asks once and persists it otherwise). Map these into `.env.local`:
`NEXT_PUBLIC_MAIN_TENANT_KEY` ← `PLATFORM`; the `NEXT_PUBLIC_*`
API URLs default to `iblai.app`. When `DOMAIN` is anything else, also map
`NEXT_PUBLIC_PLATFORM_BASE_DOMAIN` ← `DOMAIN` and
`NEXT_PUBLIC_API_BASE_URL` ← `https://api.<DOMAIN>` (plus the sign-in URL
from the session guidance when given — the auth host is not derivable from
the domain).

When the host exports `IBLAI_API_KEY`, `IBLAI_PLATFORM_KEY`, or
`IBLAI_USERNAME` (the ibl.ai desktop app does), use those values and never ask
the user for a platform API key.

`/iblai-vibe-ops-deploy` deploys through the ibl.ai platform's hosting API
(Vercel-backed) using `TOKEN` — no Vercel account, token, or CLI. It zips
the app, uploads it, polls until the build is READY, and updates `devUrl`
in `tauri.conf.json`.

## Brand

- **Primary**: `#0058cc`, **Gradient**: `linear-gradient(135deg, #00b0ef, #0058cc)`
- **Style**: shadcn/ui new-york variant, system sans-serif, Lucide icons
- SDK components ship with their own styles -- do NOT override them

## Layout Patterns

- **Page background**: `var(--sidebar-bg, #fafbfc)`
- **SDK wrappers**: Wrap SDK components in `bg-white rounded-lg border border-[var(--border-color)] overflow-hidden`
- **Responsive width**: `w-full px-4` mobile, `md:w-[75vw] md:px-0` desktop
- **Mobile safe area**: `globals.css` must have `padding-top: env(safe-area-inset-top)` (and bottom/left/right) on body, and `app/layout.tsx` metadata must include `viewport: "width=device-width, initial-scale=1, viewport-fit=cover"` -- prevents content from overlapping the iOS notch / Android status bar
- **Package manager**: Use `pnpm` (fall back to `npm`)
- **Project names**: Lowercase only — npm rejects capital letters in package names. Convert any name the user gives (e.g. `MyApp` → `my-app`) before passing to `create-next-app` or `vibe-starter`.

## Commands

```bash
pnpm dev             # Dev server
pnpm build           # Production build
pnpm typecheck       # Type-check
```

Add features with the `/iblai-vibe-*` skills (they create the files directly).

---

## Step 3: Add Frontend Design Skill

After writing the CLAUDE.md, use the AskUserQuestion tool to ask:

**Question:** "Add the Anthropic frontend design skill? It helps produce higher-quality UI with consistent design patterns, responsive layouts, and accessibility."

**Options:**
- Yes
- No

If the user selects Yes, run the following command (do not print it):

```bash
npx skills add https://github.com/anthropics/skills --skill frontend-design --yes
```

## Step 4: Create `.npmrc` to prevent supply chain attacks
Create `.npmrc` in the current directory and add the content below:
```
min-release-age=7
minimum-release-age=10080
save-exact=true
```
## Step 5: Confirm

After writing the file, tell the user:

> Updated `CLAUDE.md` with ibl.ai platform guidance. Claude Code will now
> prioritize ibl.ai SDK components over custom implementations and use the
> correct skills when adding features.