# Migrating an entrepta project to v4

> For a coding agent working in a project that uses entrepta 3.x. entrepta 4 takes the mark out of the defaults: the ◆ and the // go, and the editor look leaves the library. Nothing is lost: each change to the look says how to bring the old one back. Check the app at 375px, in dark and light, after each step.

## 1. Update the files

The CLI copies source, so nothing updates on its own. Commit first: `--overwrite` replaces local edits.

```bash
# the new tokens: --finish-glow, --chart-from and the taylor theme
npx @entrepta/cli@latest init --theme=entrepta --overwrite

# the components that changed. Commit first: --overwrite replaces your edits
npx @entrepta/cli@latest add card dialog field metric choice-card swatch-picker \
  chat-thread tabs stepper sidebar mobile-nav dropdown command-palette tooltip \
  segmented-control empty-state --overwrite

# the format file has a new name. Reinstall what uses it, then delete lib/format.ts
# if it was entrepta's
npx @entrepta/cli@latest add amount delta money-input calendar date-picker \
  date-navigator filter-builder bar-list contribution-grid chart --overwrite
```

## 2. What changed

### Labels

Before: CardLabel, FieldLabel, DialogLabel, Metric, ChoiceCard, SwatchPicker and ChatThread put a ◆ in front of their text.

After: They draw nothing in front. Pass an icon for something there, a Phosphor icon or an element.

To bring the old look back:

```tsx
const Mark = () => (
  <span aria-hidden style={{ fontSize: 10 }} className="text-[var(--fg-brand)]">◆</span>
)

<CardLabel icon={<Mark />}>post</CardLabel>
<Field id="email" label="email" icon={<Mark />}>…</Field>
<Metric label="spent" icon={<Mark />} value={…} />
```

### The current marker

Before: Sidebar, MobileNav, Stepper and Tabs marked the current item with a ◆.

After: Sidebar and MobileNav take an indicator, a dot by default. Tabs and Stepper have none by default: the underline and the marker already say it. null hides it.

To bring the old look back:

```tsx
const Mark = () => (
  <span aria-hidden style={{ fontSize: 10 }} className="text-[var(--fg-brand)]">◆</span>
)

<Sidebar indicator={<Mark />} … />
<MobileNav indicator={<Mark />} … />
<Tabs indicator={<Mark />} defaultValue="a">…</Tabs>
<Stepper indicator={<Mark />} steps={STEPS} current="bank" />
```

### Menu titles

Before: DropdownMenuLabel and a command palette group had a ◆ before the title.

After: They are text.

To bring the old look back:

```tsx
// a class on the label, the way the ◆ came in before
<DropdownMenuLabel className="before:content-['◆'] before:text-[var(--fg-brand)] before:[font-size:9px]">
  account
</DropdownMenuLabel>
<CommandGroup
  heading="pages"
  className="[&_[cmdk-group-heading]]:before:content-['◆'] [&_[cmdk-group-heading]]:before:text-[var(--fg-brand)]"
/>
```

### The //

Before: FieldError and the command palette footer started with a dimmed //.

After: FieldError is the message alone. The palette footer says palette.

To bring the old look back:

```tsx
const Slashes = () => <span aria-hidden className="opacity-70">{"// "}</span>

<Field id="email" label="email" error={error && <><Slashes />{error}</>}>…</Field>
<CommandFoot><Slashes />palette</CommandFoot>
```

### CardComment

Before: CardComment drew a // in front of a footer note.

After: It is CardNote now, the text alone in the footer's ink.

To bring the old look back:

```tsx
<CardNote>
  <span aria-hidden className="opacity-60">{"// "}</span>
  updated today
</CardNote>
```

### lib/format.ts

Before: The format helpers lived in lib/format.ts, a name many projects already use.

After: They live in lib/entrepta-format.ts. Reinstall what imports them, then delete lib/format.ts if it was entrepta's. Never delete one that is yours.

## 3. What was removed

| removed | instead |
| --- | --- |
| StatusBar | Moved to the docs app (apps/docs/components/editor/status-bar.tsx). Copy it from there. It is the bar at the bottom of this site. |
| ChromeMessage | Use EmptyState with size="page". It takes an illustration and a heading level. |
| SectHead, doc-parts | Removed. Nothing used them. They were the $ command rule and the heading pieces. |
| PageOutline | Removed. Nothing used it. |
| PageLoading | Removed, with the load-dot classes. Use Skeleton for a loading shape. |
| Spotlight, SpotlightCard | Removed, with the --bg-spotlight token. The glow that follows the cursor is gone. SpotlightCard is Card. |
| Card variant terminal, CardTerminalBar, CardTerminalBody | Removed. A block of shell commands is CodeBlock variant="terminal". Anything else is a Card. |
| Tabs onClose | Removed. A tab is picked, not closed. The × button is gone. |
| Tabs variant="window" | Removed. The title bar with the three dots is gone from the docs site too. A plain TabsList is the tabs. |

`add` says so when asked for one of them, and links this page.

## 4. What is new

- **taylor.** A seventh theme with no hue: the brand is white on dark and black on light, and cards and overlays carry no brand glow. Every ink is measured like the others.
- **--finish-glow.** How much brand light the finish carries, from 0 to 1. It scales the corner glow of cards and overlays and the lift of a hovered card. Any theme or project sets it once.
- **--chart-from.** Where the chart colors start turning. It is the brand, unless a theme with no hue names one.
- **EmptyState.** size="page" is a whole screen, such as a 404 or an error. It takes an illustration and a headingLevel.
- **ChatThread.** An avatar for each role, or for one message.
- **Stepper.** Each step takes an icon for its marker, a number when it has none. The vertical one draws its lines.
- **Tooltip.** It follows the mode of the page, light on a light page. surface="dark" keeps it near black.
- **SegmentedControl.** shape="pill", and truncate={false} so a segment grows to its word.
- **Sidebar.** The rail's tooltip clears the rail's border, and an indicator replaces the dot.
- **Field.** The star of a required label is drawn by CSS, so a test finds the label by its name.
- **The CLI.** add says when an item was removed and where to look, and the init prompt offers taylor.