# Lovable

> Wire Lovable to respect your kit's conventions via lovable.md or pinned context.

[Lovable](https://lovable.dev) doesn't have a project-root config file like Claude Code or
Cursor — it relies on chat-pinned context. OTF kits ship a `lovable.md` you can copy into
Lovable's "knowledge" or "instructions" panel, plus links to the live demo + GitHub repo so
Lovable's web-fetch can read them.

## How OTF + Lovable plays out

Two patterns, depending on what you're doing:

### 1. Open the kit in Lovable directly

When importing a kit into Lovable as a starter:

1. Connect the GitHub repo (`otf-kit/saas-dashboard` or `otf-kit/fitness-kit`)
2. Paste the contents of `lovable.md` into Lovable's instructions panel
3. Tell Lovable "follow the conventions in the instructions when adding screens or components"

### 2. Use Lovable to scaffold something OTF-shaped

When starting fresh in Lovable but wanting OTF idioms:

1. Tell Lovable "I want to use @otfdashkit/ui (npm). Install it, import the tokens CSS first,
   then the component CSS"
2. Paste the relevant section of `lovable.md`
3. Reference the [Getting started](/docs/getting-started) page so Lovable knows the load order

## What goes in lovable.md

Lovable responds best to **directive prose**, not tables or rule lists. Phrase it as:

```md title="kits/<your-kit>/lovable.md"
# Lovable instructions — OTF SaaS Dashboard kit

You are editing the OTF SaaS Dashboard kit. The stack is Vite 6 + React 19 +
TanStack Router + TanStack Query + Hono 4 + Bun + Postgres + Drizzle + Better Auth
+ @otfdashkit/ui.

When adding a new screen:
1. Create `src/pages/home/<name>.tsx`
2. Wrap content in `<FadeIn>` then `<Page>` / `<PageHeader>` / `<PageBody>` from @otfdashkit/ui
3. Add the route in `src/main.tsx` via `createRoute(...)`
4. Add to `homeLayoutRoute.addChildren([...])`
5. Add a sidebar item in `src/components/Sidebar.tsx`

Theming is token-based. Always use Tailwind utility classes like `bg-background`,
`text-foreground`, `border-border`, `bg-card`, `bg-primary`. Never hardcode hex.

When fetching data, copy the optimistic-update pattern from `src/hooks/useProjects.ts`:
useQuery for reads, useMutation with onMutate (cancel queries, snapshot, optimistic update),
onError (rollback), onSettled (invalidate).

When adding a Hono server route, copy the shape from `server/routes/projects.ts`:
GET / · GET /:id · POST · PATCH /:id · DELETE /:id, all using Drizzle.

Mock data must use fictional names (Sarah Chen, Alex Rivera, Jordan Kim).
Never check in real names.

Strict TypeScript. No `any`, no `as` casts. Functional components only.
Don't add comments unless explaining a non-obvious why.

Demo login: demo@otf-kit.dev / demo-user-pw-1234.
```

## Tips for Lovable-specific behavior

- **Lovable loves examples.** The more you anchor instructions to existing files in the repo,
  the better the output. "Copy the shape of `useProjects.ts`" beats "follow the optimistic
  update pattern".

- **Repeat the rules per turn.** Lovable's context window is shorter than Claude Code's, and
  pinned instructions can drop. If you're doing a multi-step refactor, restate the rule each
  turn.

- **Lovable can fetch URLs.** If the doc you need lives at `otf-kit.dev/docs/...`, just
  paste the URL — Lovable will fetch and read it.