Lovable

npm install @arcyai/sdk

VITE_ARCY_PUBLISHABLE_KEY=pk_live_YOUR_KEY_HERE

# Integrate the ARCY SDK into this project

Install `@arcyai/sdk` and do a complete, working integration. Follow every phase in order.

---

## Phase 1: Install the package

Add `@arcyai/sdk` to the project dependencies.

---

## Phase 2: Set up environment variables

Add these to the project environment variables:

```
VITE_ARCY_PUBLISHABLE_KEY=pk_live_YOUR_KEY_HERE
```

Leave the placeholder value. The developer will replace it with their real key from app.arcyai.com.

The secret key (`ARCY_SECRET_KEY`) is for CLI use only. Do not add it to the client environment.

---

## Phase 3: Wrap the app in ARCYProvider

`ARCYProvider` must wrap the entire app. It needs the `publicKey` prop always, and `userId` plus `userTraits` when a logged-in user is available. This is how ARCY ties sessions to real users in the dashboard.

### CRITICAL RULES FOR WRAPPING

1. **Read the existing root component first.** Identify every provider already wrapping the app content (e.g. QueryClientProvider, ThemeProvider). ArcyWrapper must be placed INSIDE the existing provider tree, as the innermost wrapper around the app content. Never place it outside auth providers or it will lose access to auth context.

2. **Preserve all existing code.** Do not remove, reorder, or simplify existing imports, providers, or any other code. Only add the ArcyWrapper. Show a diff or clearly mark what was added vs what existed.

3. **Style import path:** The styles import is `@arcyai/sdk/styles`. If this import causes a build error, try `@arcyai/sdk/dist/styles.css` as a fallback, then `@arcyai/sdk/styles.css`. Log which one worked.

Choose the correct implementation based on the auth setup in this project:

### With Supabase auth

Add `ArcyWrapper` to `src/App.tsx` or the root component. Wrap your existing content INSIDE the existing provider tree:

```tsx
import { useUser } from "@supabase/auth-helpers-react"
import { ARCYProvider } from "@arcyai/sdk/react"
import "@arcyai/sdk/styles"

function ArcyWrapper({ children }: { children: React.ReactNode }) {
  const user = useUser()
  return (
    <ARCYProvider
      publicKey={import.meta.env.VITE_ARCY_PUBLISHABLE_KEY}
      userId={user?.id ?? undefined}
      userTraits={user?.email ? { email: user.email } : undefined}
    >
      {children}
    </ARCYProvider>
  )
}
```

Wrap the root return with `<ArcyWrapper>` INSIDE existing providers:

```tsx
export default function App() {
  return (
    <ExistingProvider>
      <ArcyWrapper>
        {/* existing app content */}
      </ArcyWrapper>
    </ExistingProvider>
  )
}
```

### With Clerk auth

```tsx
import { useUser } from "@clerk/clerk-react"
import { ARCYProvider } from "@arcyai/sdk/react"
import "@arcyai/sdk/styles"

function ArcyWrapper({ children }: { children: React.ReactNode }) {
  const { user, isLoaded } = useUser()
  if (!isLoaded) return <>{children}</>
  return (
    <ARCYProvider
      publicKey={import.meta.env.VITE_ARCY_PUBLISHABLE_KEY}
      userId={user?.id ?? undefined}
      userTraits={
        user?.primaryEmailAddress
          ? { email: user.primaryEmailAddress.emailAddress }
          : undefined
      }
    >
      {children}
    </ARCYProvider>
  )
}
```

### With custom auth (useAuth hook or similar)

Read what hook or context provides the current user. Extract `userId` and `email` from it. Then:

```tsx
import { ARCYProvider } from "@arcyai/sdk/react"
import "@arcyai/sdk/styles"

function ArcyWrapper({ children }: { children: React.ReactNode }) {
  const { user } = useAuth() // replace with whatever provides the current user
  return (
    <ARCYProvider
      publicKey={import.meta.env.VITE_ARCY_PUBLISHABLE_KEY}
      userId={user?.id ?? undefined}
      userTraits={user?.email ? { email: user.email } : undefined}
    >
      {children}
    </ARCYProvider>
  )
}
```

### No auth

```tsx
import { ARCYProvider } from "@arcyai/sdk/react"
import "@arcyai/sdk/styles"

function ArcyWrapper({ children }: { children: React.ReactNode }) {
  return (
    <ARCYProvider publicKey={import.meta.env.VITE_ARCY_PUBLISHABLE_KEY}>
      {children}
    </ARCYProvider>
  )
}
```

---

## Phase 4: Add data-arcy attributes

Read EVERY page, layout, and component in the project. Add `data-arcy` attributes to ALL interactive and semantically important elements. These IDs tell the AI assistant where things are so it can highlight them, scroll to them, and guide users to them. More anchors = better AI accuracy. Fewer anchors = blind spots where the AI cannot point users to the right place.

### Rules

**Naming:**
- Use lowercase hyphen-separated IDs that describe what the element does: `create-project-button`, not `top-right-button`
- For repeated/mapped elements (e.g. sidebar nav items, list rows), include the distinguishing identifier: `nav-dashboard`, `nav-settings`, not just `nav-item`
- Each `data-arcy` value must be GLOBALLY UNIQUE across the entire project. No two elements may share the same ID.

**What to annotate (annotate ALL of these, not a subset):**
- Every navigation link and menu item
- Every primary and secondary action button (create, save, delete, cancel, submit, invite, upgrade)
- Every form and its submit button
- Every input field the user interacts with (search, filters, text inputs, selects, toggles)
- Every section/container that represents a distinct functional area
- Every empty state and its CTA
- Every modal/dialog trigger button and the elements inside it
- Every card or list item that represents a core entity

**Conditional/dynamic elements:**
- For elements inside modals, drawers, or conditionally rendered blocks: add `data-arcy` to BOTH the trigger button AND the elements inside. Document which anchors are conditional in the route YAML `elements` array (Phase 5).
- For elements rendered via `.map()` over dynamic data: add `data-arcy` with a template pattern:
  ```tsx
  {projects.map(p => (
    <div key={p.id} data-arcy={`project-card-${p.slug}`}>...</div>
  ))}
  ```

**There is no upper limit on the number of anchors.** Cover everything. The AI's ability to help users depends directly on anchor coverage.

```tsx
<button data-arcy="create-project-button">Create project</button>
<nav data-arcy="main-sidebar">
  <a href="/dashboard" data-arcy="nav-dashboard">Dashboard</a>
  <a href="/settings" data-arcy="nav-settings">Settings</a>
</nav>
<button data-arcy="upgrade-plan-button">Upgrade plan</button>
<input data-arcy="global-search-input" type="search" />
<button data-arcy="open-create-modal">New item</button>
<dialog data-arcy="create-item-modal">
  <input data-arcy="create-item-name-input" />
  <button data-arcy="create-item-submit">Create</button>
</dialog>
```

Keep a complete list of every `data-arcy` ID you add, noting which are conditional and which are dynamic. You need this list in Phase 5.

---

## Phase 5: Generate the `.arcy/` knowledge graph

Create the `.arcy/` directory at the project root. This is the ARCY backend's knowledge base: what the product is, what each page does, the domain entities, and guided walkthroughs. The backend reads these YAML files at query time to give accurate, product-specific answers.

Fill in the content by reading the project files. Do not use generic placeholders for the app name or feature descriptions.

### Create `.arcy/app.yaml` (required)

This file is always injected into every AI response. Every field you omit is context the AI will not have.

```yaml
app:
  name: "[actual app name from the project]" # required
  description: "[what this app does and who uses it — 1-2 sentences from the project]" # required

navigation: # optional but strongly recommended — add every route you found
  - path: /dashboard
    label: Dashboard
    description: "[what this page does]"
  # continue for every route in the project

terminology: # optional — product-specific vocabulary
  - term: "[domain-specific term]"
    definition: "[what it means in this specific product]"

personas: # optional — user types
  - id: admin
    name: Admin
    description: "[what this user type does in the product]"
```

### Create `.arcy/routes/[slug].yaml` for each distinct route

The slug is the first path segment: `/settings/team` → `settings.yaml`. File names must be `[a-z0-9-]+.yaml`.

```yaml
route:
  path: /dashboard # required
  label: Dashboard # required
  description: "[what this page does]"
  purpose: "[what a user comes here to accomplish]"

sections: # optional — distinct functional areas on this page
  - id: overview
    label: "[section name]"
    anchorId: "[data-arcy ID of this section from Phase 4]"
    description: "[what this section shows or does]"
    elements:
      - anchorId: "[data-arcy ID of an interactive element in this section]"
        label: "[element label]"
        type: button
        description: "[what this element does]"

help: # optional
  summary: "[one sentence describing the page]"
  faq:
    - question: "[common user question about this page]"
      answer: "[answer]"
      relatedElements: ["[data-arcy ID]"]
```

### Create `.arcy/entities/[id].yaml` for core domain entities (optional)

Only create these for the main domain objects. Skip if the project has no complex entities.

```yaml
entity:
  id: project # required
  name: Project # required
  description: "[what this entity is in the product]"

fields: # optional
  - id: status
    label: Status
    type: enum
    description: "[what this field controls]"
    enumValues:
      - value: active
        label: Active
        description: "[what active means in this product]"
```

### Create `.arcy/flows/[id].yaml` for guided walkthroughs

Create at least 2 flows:
1. **`onboarding`** — walks a new user through the first-time experience
2. A **feature discovery** flow for a core feature users commonly miss

Steps with `anchorId` are executable by Teach mode (the AI highlights those elements in sequence). Steps without `anchorId` are AI context only. Both are valid.

```yaml
flow:
  id: onboarding # required — lowercase, matches the file name
  name: Get Started # required
  description: "[what this flow helps the user accomplish]"
  goal: "[what the user wants to achieve — e.g. 'Create your first project']"
  persona: admin # optional — target user type

steps:
  - order: 1
    title: "[step title]"
    description: "[what the user sees or does here]"
    route: /dashboard # optional — the page this step is on
    action: "[text description of what to do]"
    anchorId: main-sidebar # optional — enables Teach mode, must match a data-arcy ID from Phase 4
  - order: 2
    title: "[next step title]"
    description: "[what the user does next]"
    route: /dashboard
    action: "Click here to [primary action description]"
    anchorId: create-project-button
```

CRITICAL rules for flow `anchorId` values:
- Every `anchorId` must match a `data-arcy` ID you added in Phase 4
- Only use `anchorId` for elements always in the DOM on that route
- Never reference elements inside modals unless a previous step opens that modal first

After creating all files, the structure should look like:

```
.arcy/
  app.yaml
  routes/
    dashboard.yaml
    settings.yaml
    [other route slugs].yaml
  entities/
    [entity-id].yaml    (if applicable)
  flows/
    onboarding.yaml
    [feature-discovery-id].yaml
```

---

## Phase 6: Verify

Confirm all of the following before finishing:

1. `ARCYProvider` wraps the entire app, INSIDE any existing provider tree
2. `@arcyai/sdk/styles` is imported in the provider file (confirm import does not cause build errors)
3. `VITE_ARCY_PUBLISHABLE_KEY` is set in the project environment variables
4. `.arcy/app.yaml` exists with `app.name` and `app.description` filled in (no placeholder values remaining)
5. Route YAML files exist in `.arcy/routes/` for each distinct route in the project
6. At least 2 flow YAML files exist in `.arcy/flows/`
7. `data-arcy` attributes comprehensively cover the app (every nav item, every action button, every form field, every section container, every entity card/row)
8. Every `data-arcy` value is globally unique across the codebase (run a grep to verify: `grep -roh 'data-arcy="[^"]*"' src/ | sort | uniq -d` should return empty)
9. Flow step `anchorId` values reference `data-arcy` IDs you added in Phase 4
10. No flow step `anchorId` references an element inside a modal unless a previous step opens it

Print a summary of:
- Every file changed (with what was changed)
- Total number of `data-arcy` attributes added
- Every `.arcy/` YAML file created (key content: app name, route count, flow names and step counts)
- Any warnings (e.g. conditional anchors referenced in flows, auth library not found)

arcy push
arcy status