# /iblai-vibe-start

> Mirrored from [`iblai/vibe`](https://github.com/iblai/vibe) · [`skills/start/iblai-vibe-start/SKILL.md`](https://github.com/iblai/vibe/blob/main/skills/start/iblai-vibe-start/SKILL.md). This page is generated — edit it in the repository, not here.

Ask four questions, write the answers down, route. Every later skill reads
the answers instead of asking again. Takes two minutes; prevents the two
expensive mistakes (building a single-org app that needed to be multi-org,
and wiring SSO into something that only needed a server token).

> Words: [docs/glossary.md](https://raw.githubusercontent.com/iblai/vibe/refs/heads/main/docs/glossary.md).
> Sign-in mechanics and the three architectures in full: [docs/auth-model.md](https://raw.githubusercontent.com/iblai/vibe/refs/heads/main/docs/auth-model.md).
> The entities every app is built on: [docs/domain-model.md](https://raw.githubusercontent.com/iblai/vibe/refs/heads/main/docs/domain-model.md).

## Step 0: Skip what is already answered

Read `iblai.env` if it exists. These keys are the record of this conversation;
any that are present are settled — ask only the missing ones:

```
PROJECT=new | existing
ARCHITECTURE=single-org | multi-org | headless
ACCESS=members | public | none
DOMAIN_FOCUS=users,memories,agents,organizations   # comma-separated subset
```

If all four are present, say so in one line and go to **Step 5**.

## Step 1: New or existing?

> Is this a **new project**, or am I adding ibl.ai to an **existing** codebase?

- Look before asking: no `package.json` → new. A `package.json` with `next` →
  existing Next.js app. Anything else (Vite, Remix, Expo, a Python backend) →
  existing, and note the framework — the `ui` skills target Next.js; the `api`
  skills work anywhere.

## Step 2: One organization, many, or none?

> Who is this for?
> - **One organization** — mine, or one customer I deploy it to. Members sign in; the app is pinned to that org. *(most apps)*
> - **Many organizations** — one deployment, users move between orgs, like os.ibl.ai.
> - **No sign-in at all** — a script, a CI job, or my own backend calling the platform.

Map to `ARCHITECTURE=single-org | multi-org | headless`. Explain in one
sentence why it matters: single-org pins the org key and uses one
server-to-server token; multi-org puts the org in the URL and re-authenticates
per org; headless never touches SSO. Recommend **single-org** when unsure —
everything carries over to multi-org later.

## Step 3: Who signs in?

Skip when `ARCHITECTURE=headless` (`ACCESS=none`).

> Who reaches the app?
> - **Members only** — people who belong to the organization (invited, or self-joined). *(default)*
> - **The public too** — at least one agent is reachable without an account (a public assistant, a lead-capture bot, a demo).

Map to `ACCESS=members | public`. `public` means: mark that agent
`allow_anonymous` and leave its route out of `AuthProvider`'s protection
(docs/auth-model.md §4).

## Step 4: What is it about?

> Which of these does the app revolve around? Pick all that apply:
> - **Users** — profiles, per-user settings, roles and admins
> - **Memories** — the app remembers things about each person; agents personalize
> - **Agents** — creating or configuring agents, not just chatting with one
> - **Organizations** — org-level settings, branding, billing, many customers

Map to `DOMAIN_FOCUS=…`. Most apps say "users and agents"; that is fine.

## Step 5: Record and route

1. Write the four keys to `iblai.env` (create the file from
   `iblai.env.example` when missing; keep existing lines).
2. If a project `CLAUDE.md` / `AGENTS.md` exists, add or replace a
   `## Decisions` block:

   ```markdown
   ## Decisions (from /iblai-vibe-start)
   - Project: new | existing (<framework>)
   - Architecture: single-org | multi-org | headless — <one line why>
   - Access: members | public (<which agent is public>) | none
   - Focus: users, memories, agents, organizations
   ```

3. Credentials: run `/iblai-vibe-connect` (browser round trip; falls back to
   manual questions). Skip it when `iblai.env` already holds a real `PLATFORM`
   and `TOKEN`, or the host exports `IBLAI_API_KEY`.

4. Route — say which skill you are opening and why:

| Answers | Next |
|---|---|
| `new` + `single-org` | `/iblai-vibe-ops-init` — vibe-starter already is this architecture (pinned org, `/setup`, admin area, user + org settings) |
| `new` + `multi-org` | `/iblai-vibe-ops-init`, then `/iblai-vibe-auth` → "Going multi-org" (the OS pattern: org in the URL, `TenantSwitcher`, per-agent anonymous rule) |
| `existing` Next.js + `single-org` / `multi-org` | `/iblai-vibe-auth` (providers, store, SSO callback), then the feature skills for the focus |
| `existing` non-Next.js, any `ACCESS` | The `api` family: `/iblai-api-login`, then `/iblai-vibe-api`'s server-route pattern adapted to the framework; the SDK's React components need Next.js |
| `headless` | `/iblai-api-login`, then the `iblai-api-*` skill per family; `tutorials/` for end-to-end recipes |
| `ACCESS=public` (any) | after the above: `/iblai-vibe-agent-setting` (`allow_anonymous`) and `docs/auth-model.md` §4 |

5. Then by focus:

| Focus | Open |
|---|---|
| users | `/iblai-vibe-profile` ★, `/iblai-vibe-user-metadata` ★, `/iblai-vibe-admin` |
| memories | `/iblai-vibe-memory-guide` ★ |
| agents | `/iblai-vibe-agent-create` ★ → `/iblai-vibe-agent-setting` ★ → `/iblai-vibe-agent` |
| organizations | `/iblai-vibe-org-metadata` ★, `/iblai-vibe-account`, `/iblai-vibe-pricing` |

Always finish with `/iblai-vibe-ops-test` — build, tests and its touch test in a
real browser — before showing work or calling it done, and mention
`/iblai-vibe-ops-deploy` / `/iblai-vibe-ops-build` as the way to ship.

## Notes

- Never ask for a password, and never for the Platform API Token before
  `/iblai-vibe-ops-init` or `/iblai-api-login` needs it (they say where it
  comes from).
- The answers are not permanent: re-run this skill to change them; the
  record in `iblai.env` is the source of truth for later skills.
- Installed skills are a copy — if `.claude/skills/iblai-vibe/SKILL.md` is
  older than two weeks, suggest `/iblai-vibe-ops-upgrade` first.