velloo 0.4.1 → 0.6.0

package/pkgs/shadcn-snapshot/src/components/ui/empty.tsx

@@ -1,9 +1,7 @@
 // Vendored from shadcn-ui (https://ui.shadcn.com/docs/components/radix/empty).
-// Snapshot version: see packages/shadcn-snapshot/package.json#snapshotVersion.
-// Regenerate with `bun run vendor` — do not hand-edit unless you are adding a
-// canvas adaptation, in which case add the id to vendor.ts's ADAPTED set.
+// Design-mode fork for the Velloo canvas — not the shadcn the IDE chrome renders.
+// Regenerate with `bun run vendor` — the pipeline is scripts/vendor-shadcn/.
 import { cva, type VariantProps } from "class-variance-authority";
-
 import { cn } from "../../lib/utils.ts";
 
 function Empty({ className, ...props }: React.ComponentProps<"div">) {

package/pkgs/shadcn-snapshot/src/components/ui/field.tsx

@@ -1,13 +1,12 @@
 // Vendored from shadcn-ui (https://ui.shadcn.com/docs/components/radix/field).
-// Snapshot version: see packages/shadcn-snapshot/package.json#snapshotVersion.
-// Regenerate with `bun run vendor` — do not hand-edit unless you are adding a
-// canvas adaptation, in which case add the id to vendor.ts's ADAPTED set.
+// Design-mode fork for the Velloo canvas — not the shadcn the IDE chrome renders.
+// Regenerate with `bun run vendor` — the pipeline is scripts/vendor-shadcn/.
 "use client";
 
 import { cva, type VariantProps } from "class-variance-authority";
 import { useMemo } from "react";
-
 import { cn } from "../../lib/utils.ts";
+
 import { Label } from "./label.tsx";
 import { Separator } from "./separator.tsx";
 

package/pkgs/shadcn-snapshot/src/components/ui/input-group.tsx

@@ -1,13 +1,12 @@
 // Vendored from shadcn-ui (https://ui.shadcn.com/docs/components/radix/input-group).
-// Snapshot version: see packages/shadcn-snapshot/package.json#snapshotVersion.
-// Regenerate with `bun run vendor` — do not hand-edit unless you are adding a
-// canvas adaptation, in which case add the id to vendor.ts's ADAPTED set.
+// Design-mode fork for the Velloo canvas — not the shadcn the IDE chrome renders.
+// Regenerate with `bun run vendor` — the pipeline is scripts/vendor-shadcn/.
 "use client";
 
 import { cva, type VariantProps } from "class-variance-authority";
 import type * as React from "react";
-
 import { cn } from "../../lib/utils.ts";
+
 import { Button } from "./button.tsx";
 import { Input } from "./input.tsx";
 import { Textarea } from "./textarea.tsx";

package/pkgs/shadcn-snapshot/src/components/ui/item.tsx

@@ -1,13 +1,12 @@
 // Vendored from shadcn-ui (https://ui.shadcn.com/docs/components/radix/item).
-// Snapshot version: see packages/shadcn-snapshot/package.json#snapshotVersion.
-// Regenerate with `bun run vendor` — do not hand-edit unless you are adding a
-// canvas adaptation, in which case add the id to vendor.ts's ADAPTED set.
+// Design-mode fork for the Velloo canvas — not the shadcn the IDE chrome renders.
+// Regenerate with `bun run vendor` — the pipeline is scripts/vendor-shadcn/.
 
 import { cva, type VariantProps } from "class-variance-authority";
 import { Slot } from "radix-ui";
 import type * as React from "react";
-
 import { cn } from "../../lib/utils.ts";
+
 import { Separator } from "./separator.tsx";
 
 function ItemGroup({ className, ...props }: React.ComponentProps<"div">) {

package/pkgs/shadcn-snapshot/src/components/ui/kbd.tsx

@@ -1,7 +1,6 @@
 // Vendored from shadcn-ui (https://ui.shadcn.com/docs/components/radix/kbd).
-// Snapshot version: see packages/shadcn-snapshot/package.json#snapshotVersion.
-// Regenerate with `bun run vendor` — do not hand-edit unless you are adding a
-// canvas adaptation, in which case add the id to vendor.ts's ADAPTED set.
+// Design-mode fork for the Velloo canvas — not the shadcn the IDE chrome renders.
+// Regenerate with `bun run vendor` — the pipeline is scripts/vendor-shadcn/.
 import { cn } from "../../lib/utils.ts";
 
 function Kbd({ className, ...props }: React.ComponentProps<"kbd">) {

package/pkgs/shadcn-snapshot/src/components/ui/label.tsx

@@ -1,12 +1,10 @@
 // Vendored from shadcn-ui (https://ui.shadcn.com/docs/components/radix/label).
-// Snapshot version: see packages/shadcn-snapshot/package.json#snapshotVersion.
-// Regenerate with `bun run vendor` — do not hand-edit unless you are adding a
-// canvas adaptation, in which case add the id to vendor.ts's ADAPTED set.
+// Design-mode fork for the Velloo canvas — not the shadcn the IDE chrome renders.
+// Regenerate with `bun run vendor` — the pipeline is scripts/vendor-shadcn/.
 "use client";
 
 import { Label as LabelPrimitive } from "radix-ui";
 import type * as React from "react";
-
 import { cn } from "../../lib/utils.ts";
 
 function Label({ className, ...props }: React.ComponentProps<typeof LabelPrimitive.Root>) {

package/pkgs/shadcn-snapshot/src/components/ui/marker.tsx

@@ -1,12 +1,10 @@
 // Vendored from shadcn-ui (https://ui.shadcn.com/docs/components/radix/marker).
-// Snapshot version: see packages/shadcn-snapshot/package.json#snapshotVersion.
-// Regenerate with `bun run vendor` — do not hand-edit unless you are adding a
-// canvas adaptation, in which case add the id to vendor.ts's ADAPTED set.
+// Design-mode fork for the Velloo canvas — not the shadcn the IDE chrome renders.
+// Regenerate with `bun run vendor` — the pipeline is scripts/vendor-shadcn/.
 
 import { cva, type VariantProps } from "class-variance-authority";
 import { Slot } from "radix-ui";
 import type * as React from "react";
-
 import { cn } from "../../lib/utils.ts";
 
 const markerVariants = cva(

package/pkgs/shadcn-snapshot/src/components/ui/message.tsx

@@ -1,9 +1,7 @@
 // Vendored from shadcn-ui (https://ui.shadcn.com/docs/components/radix/message).
-// Snapshot version: see packages/shadcn-snapshot/package.json#snapshotVersion.
-// Regenerate with `bun run vendor` — do not hand-edit unless you are adding a
-// canvas adaptation, in which case add the id to vendor.ts's ADAPTED set.
+// Design-mode fork for the Velloo canvas — not the shadcn the IDE chrome renders.
+// Regenerate with `bun run vendor` — the pipeline is scripts/vendor-shadcn/.
 import type * as React from "react";
-
 import { cn } from "../../lib/utils.ts";
 
 function MessageGroup({ className, ...props }: React.ComponentProps<"div">) {

package/pkgs/shadcn-snapshot/src/components/ui/native-select.tsx

@@ -1,11 +1,9 @@
 // Vendored from shadcn-ui (https://ui.shadcn.com/docs/components/radix/native-select).
-// Snapshot version: see packages/shadcn-snapshot/package.json#snapshotVersion.
-// Regenerate with `bun run vendor` — do not hand-edit unless you are adding a
-// canvas adaptation, in which case add the id to vendor.ts's ADAPTED set.
+// Design-mode fork for the Velloo canvas — not the shadcn the IDE chrome renders.
+// Regenerate with `bun run vendor` — the pipeline is scripts/vendor-shadcn/.
 
 import { ChevronDownIcon } from "lucide-react";
 import type * as React from "react";
-
 import { cn } from "../../lib/utils.ts";
 
 type NativeSelectProps = Omit<React.ComponentProps<"select">, "size"> & {

package/pkgs/shadcn-snapshot/src/components/ui/navigation-menu.tsx

@@ -1,13 +1,11 @@
 // Vendored from shadcn-ui (https://ui.shadcn.com/docs/components/radix/navigation-menu).
-// Snapshot version: see packages/shadcn-snapshot/package.json#snapshotVersion.
-// Regenerate with `bun run vendor` — do not hand-edit unless you are adding a
-// canvas adaptation, in which case add the id to vendor.ts's ADAPTED set.
+// Design-mode fork for the Velloo canvas — not the shadcn the IDE chrome renders.
+// Regenerate with `bun run vendor` — the pipeline is scripts/vendor-shadcn/.
 
 import { cva } from "class-variance-authority";
 import { ChevronDownIcon } from "lucide-react";
 import { NavigationMenu as NavigationMenuPrimitive } from "radix-ui";
 import type * as React from "react";
-
 import { cn } from "../../lib/utils.ts";
 
 function NavigationMenu({

package/pkgs/shadcn-snapshot/src/components/ui/pagination.tsx

@@ -1,12 +1,11 @@
 // Vendored from shadcn-ui (https://ui.shadcn.com/docs/components/radix/pagination).
-// Snapshot version: see packages/shadcn-snapshot/package.json#snapshotVersion.
-// Regenerate with `bun run vendor` — do not hand-edit unless you are adding a
-// canvas adaptation, in which case add the id to vendor.ts's ADAPTED set.
+// Design-mode fork for the Velloo canvas — not the shadcn the IDE chrome renders.
+// Regenerate with `bun run vendor` — the pipeline is scripts/vendor-shadcn/.
 
 import { ChevronLeftIcon, ChevronRightIcon, MoreHorizontalIcon } from "lucide-react";
 import type * as React from "react";
-
 import { cn } from "../../lib/utils.ts";
+
 import { Button } from "./button.tsx";
 
 function Pagination({ className, ...props }: React.ComponentProps<"nav">) {

package/pkgs/shadcn-snapshot/src/components/ui/progress.tsx

@@ -1,12 +1,10 @@
 // Vendored from shadcn-ui (https://ui.shadcn.com/docs/components/radix/progress).
-// Snapshot version: see packages/shadcn-snapshot/package.json#snapshotVersion.
-// Regenerate with `bun run vendor` — do not hand-edit unless you are adding a
-// canvas adaptation, in which case add the id to vendor.ts's ADAPTED set.
+// Design-mode fork for the Velloo canvas — not the shadcn the IDE chrome renders.
+// Regenerate with `bun run vendor` — the pipeline is scripts/vendor-shadcn/.
 "use client";
 
 import { Progress as ProgressPrimitive } from "radix-ui";
 import type * as React from "react";
-
 import { cn } from "../../lib/utils.ts";
 
 function Progress({

package/pkgs/shadcn-snapshot/src/components/ui/radio-group.tsx

@@ -1,12 +1,10 @@
 // Vendored from shadcn-ui (https://ui.shadcn.com/docs/components/radix/radio-group).
-// Snapshot version: see packages/shadcn-snapshot/package.json#snapshotVersion.
-// Regenerate with `bun run vendor` — do not hand-edit unless you are adding a
-// canvas adaptation, in which case add the id to vendor.ts's ADAPTED set.
+// Design-mode fork for the Velloo canvas — not the shadcn the IDE chrome renders.
+// Regenerate with `bun run vendor` — the pipeline is scripts/vendor-shadcn/.
 "use client";
 
 import { RadioGroup as RadioGroupPrimitive } from "radix-ui";
 import type * as React from "react";
-
 import { cn } from "../../lib/utils.ts";
 
 function RadioGroup({

package/pkgs/shadcn-snapshot/src/components/ui/scroll-area.tsx

@@ -1,12 +1,10 @@
 // Vendored from shadcn-ui (https://ui.shadcn.com/docs/components/radix/scroll-area).
-// Snapshot version: see packages/shadcn-snapshot/package.json#snapshotVersion.
-// Regenerate with `bun run vendor` — do not hand-edit unless you are adding a
-// canvas adaptation, in which case add the id to vendor.ts's ADAPTED set.
+// Design-mode fork for the Velloo canvas — not the shadcn the IDE chrome renders.
+// Regenerate with `bun run vendor` — the pipeline is scripts/vendor-shadcn/.
 "use client";
 
 import { ScrollArea as ScrollAreaPrimitive } from "radix-ui";
 import type * as React from "react";
-
 import { cn } from "../../lib/utils.ts";
 
 function ScrollArea({

package/pkgs/shadcn-snapshot/src/components/ui/separator.tsx

@@ -1,12 +1,10 @@
 // Vendored from shadcn-ui (https://ui.shadcn.com/docs/components/radix/separator).
-// Snapshot version: see packages/shadcn-snapshot/package.json#snapshotVersion.
-// Regenerate with `bun run vendor` — do not hand-edit unless you are adding a
-// canvas adaptation, in which case add the id to vendor.ts's ADAPTED set.
+// Design-mode fork for the Velloo canvas — not the shadcn the IDE chrome renders.
+// Regenerate with `bun run vendor` — the pipeline is scripts/vendor-shadcn/.
 "use client";
 
 import { Separator as SeparatorPrimitive } from "radix-ui";
 import type * as React from "react";
-
 import { cn } from "../../lib/utils.ts";
 
 function Separator({

package/pkgs/shadcn-snapshot/src/components/ui/skeleton.tsx

@@ -1,7 +1,6 @@
 // Vendored from shadcn-ui (https://ui.shadcn.com/docs/components/radix/skeleton).
-// Snapshot version: see packages/shadcn-snapshot/package.json#snapshotVersion.
-// Regenerate with `bun run vendor` — do not hand-edit unless you are adding a
-// canvas adaptation, in which case add the id to vendor.ts's ADAPTED set.
+// Design-mode fork for the Velloo canvas — not the shadcn the IDE chrome renders.
+// Regenerate with `bun run vendor` — the pipeline is scripts/vendor-shadcn/.
 import { cn } from "../../lib/utils.ts";
 
 function Skeleton({ className, ...props }: React.ComponentProps<"div">) {

package/pkgs/shadcn-snapshot/src/components/ui/spinner.tsx

@@ -1,7 +1,6 @@
 // Vendored from shadcn-ui (https://ui.shadcn.com/docs/components/radix/spinner).
-// Snapshot version: see packages/shadcn-snapshot/package.json#snapshotVersion.
-// Regenerate with `bun run vendor` — do not hand-edit unless you are adding a
-// canvas adaptation, in which case add the id to vendor.ts's ADAPTED set.
+// Design-mode fork for the Velloo canvas — not the shadcn the IDE chrome renders.
+// Regenerate with `bun run vendor` — the pipeline is scripts/vendor-shadcn/.
 
 import { Loader2Icon } from "lucide-react";
 import { cn } from "../../lib/utils.ts";

package/pkgs/shadcn-snapshot/src/components/ui/table.tsx

@@ -1,11 +1,9 @@
 // Vendored from shadcn-ui (https://ui.shadcn.com/docs/components/radix/table).
-// Snapshot version: see packages/shadcn-snapshot/package.json#snapshotVersion.
-// Regenerate with `bun run vendor` — do not hand-edit unless you are adding a
-// canvas adaptation, in which case add the id to vendor.ts's ADAPTED set.
+// Design-mode fork for the Velloo canvas — not the shadcn the IDE chrome renders.
+// Regenerate with `bun run vendor` — the pipeline is scripts/vendor-shadcn/.
 "use client";
 
 import type * as React from "react";
-
 import { cn } from "../../lib/utils.ts";
 
 function Table({ className, ...props }: React.ComponentProps<"table">) {

package/pkgs/shadcn-snapshot/src/components/ui/tabs.tsx

@@ -1,13 +1,11 @@
 // Vendored from shadcn-ui (https://ui.shadcn.com/docs/components/radix/tabs).
-// Snapshot version: see packages/shadcn-snapshot/package.json#snapshotVersion.
-// Regenerate with `bun run vendor` — do not hand-edit unless you are adding a
-// canvas adaptation, in which case add the id to vendor.ts's ADAPTED set.
+// Design-mode fork for the Velloo canvas — not the shadcn the IDE chrome renders.
+// Regenerate with `bun run vendor` — the pipeline is scripts/vendor-shadcn/.
 "use client";
 
 import { cva, type VariantProps } from "class-variance-authority";
 import { Tabs as TabsPrimitive } from "radix-ui";
 import type * as React from "react";
-
 import { cn } from "../../lib/utils.ts";
 
 function Tabs({

package/pkgs/shadcn-snapshot/src/components/ui/toggle.tsx

@@ -1,13 +1,11 @@
 // Vendored from shadcn-ui (https://ui.shadcn.com/docs/components/radix/toggle).
-// Snapshot version: see packages/shadcn-snapshot/package.json#snapshotVersion.
-// Regenerate with `bun run vendor` — do not hand-edit unless you are adding a
-// canvas adaptation, in which case add the id to vendor.ts's ADAPTED set.
+// Design-mode fork for the Velloo canvas — not the shadcn the IDE chrome renders.
+// Regenerate with `bun run vendor` — the pipeline is scripts/vendor-shadcn/.
 "use client";
 
 import { cva, type VariantProps } from "class-variance-authority";
 import { Toggle as TogglePrimitive } from "radix-ui";
 import type * as React from "react";
-
 import { cn } from "../../lib/utils.ts";
 
 const toggleVariants = cva(

package/pkgs/shadcn-snapshot/src/shadcn-tailwind.css

@@ -1,4 +1,4 @@
-/* Vendored from shadcn@4.20.1 (dist/tailwind.css) — imported by
+/* Vendored from shadcn@4.21.0 (dist/tailwind.css) — imported by
  * tailwind-entry.css. Regenerate with `bun run vendor`; do not hand-edit.
  */
 @theme inline {

package/pkgs/shadcn-snapshot/src/tailwind-entry.css

@@ -83,7 +83,7 @@
  * Classes upstream *emits* but does not *distribute*: they live in the
  * shadcn.com app's own globals.css, so a registry pull references them without
  * ever defining them (the same leak that puts `IconPlaceholder` in the source
- * — see vendor.ts). Defined here to upstream's intent so the components that
+ * — see scripts/vendor-shadcn/). Defined here to upstream's intent so the components that
  * reference them aren't silently inert.
  */
 @utility cn-rtl-flip {

package/plugins/claude/velloo/agents/velloo-design-reviewer.md

@@ -1,9 +1,10 @@
 ---
 name: velloo-design-reviewer
 description: >-
-  Reviews Velloo screens without modifying them — dark-mode adaptation, theme
-  token discipline, contrast, layout at mobile width, and fidelity against a
-  live app page. Use after a design pass for an independent findings list.
+  Reviews Velloo screens without modifying them — the folder's own stated design
+  rules, dark-mode adaptation, theme token discipline, contrast, layout at mobile
+  width, and fidelity against a live app page. Use after a design pass for an
+  independent findings list.
 ---
 
 You are a design reviewer for a Velloo design folder. You are read-only:
@@ -11,23 +12,65 @@ screenshots, diagnostics, and annotations only. Do NOT mutate screens, snippets,
 or the theme — the one exception is `add_annotation`, to pin a finding to the
 node it concerns.
 
+Start with `get_theme`. Besides the tokens it may return `designSystem.path` —
+the design system document this folder follows, normally the repo's
+`DESIGN.md`. **Open that file and read it before looking at any screen.** Velloo
+points at it rather than copying it, so the file you read is the current one.
+Its "Do's and Don'ts" section is the house rules, and they outrank your taste.
+
 For each target screen (default: every screen on the default board):
 
-1. `screenshot mode: "compare"` — does the design actually adapt to dark
+1. **The folder's stated rules** — check the screens against the Do's and
+   Don'ts in the design system document. See below; this dimension comes first
+   because it is the only one that is not generic.
+2. `screenshot mode: "compare"` — does the design actually adapt to dark
    mode, or do raw palette colors freeze it?
-2. The screenshot's `diagnostics` — read the `theme/raw-color` entries;
+3. The screenshot's `diagnostics` — read the `theme/raw-color` entries;
    distinguish real token violations from intentional accents (`data-accent`
    nodes are exempt).
-3. `score_theme_contrast` — flag failing pairs; dark is where contrast
+4. `score_theme_contrast` — flag failing pairs; dark is where contrast
    usually breaks.
-4. `screenshot` at a mobile viewport (390 wide) — does the layout hold, or do
+5. `screenshot` at a mobile viewport (390 wide) — does the layout hold, or do
    grids overflow and type sizes collapse?
-5. If given a live URL, `compare_to_url` at the same viewport — report the
+6. If given a live URL, `compare_to_url` at the same viewport — report the
    similarity score and what the per-region refs point at. An `unverified`
    result is itself a finding: say so instead of guessing.
-6. `list_annotations` — surface unresolved designer/reviewer notes.
+7. `list_annotations` — surface unresolved designer/reviewer notes.
+
+## Reviewing against the folder's rules
+
+Work rule by rule, not screen by screen — a rule like "one accent per screen"
+is about the whole screen, and you will miss it if you are looking at nodes.
+
+**Quote the rule verbatim in every finding it produces**, copied from the file.
+The user wrote these; a finding that paraphrases them reads as your opinion, and
+the point of this dimension is that it is not.
+
+**Check only what you can actually see.** A rule is checkable when a screenshot
+or a diagnostic settles it — how many accent colors a screen uses, whether a
+flat surface carries a shadow, whether CTAs are pill-shaped, whether a heading
+uses the display face. A rule is not checkable here when it is about behavior
+(motion, transitions, hover, focus order), about content or tone, or about
+things outside the screens you were given.
+
+For an unverifiable rule, say so once in a short list at the end — "not checked:
+rules 4, 7 (both about hover states)" — and move on. Do not guess, do not
+soften it into a maybe, and do not pad the review by restating rules you did not
+test. An honest "not checked" is worth more than a speculative finding.
+
+When a rule and one of the generic dimensions disagree, report both and say
+which is which. If the folder's rule is the reason something looks wrong to
+you, the rule wins and there is no finding.
+
+If `get_theme` returns no `designSystem`, or the document has no Do's and Don'ts
+section, the folder states no rules. Say that once — it is not the same as the
+screens passing — and review the other dimensions normally. Do not invent house
+rules to fill the gap. If the path is there but you cannot open the file, say
+that too rather than reviewing as if it were empty.
+
+## Reporting
 
-Report findings ranked by severity. Each finding: screen id, node ref
-(`"@id"` or path), what is wrong, and a concrete fix. Pin the top findings
-with `add_annotation` so they're addressable on the canvas. End with the one
-thing you'd fix first.
+Report findings ranked by severity. Each finding: screen id, node ref (`"@id"`
+or path), what is wrong, and a concrete fix. A rule-based finding also carries
+the quoted rule. Pin the top findings with `add_annotation` so
+they're addressable on the canvas. End with the one thing you'd fix first.

package/plugins/claude/velloo/agents/velloo-designer.md

@@ -16,7 +16,10 @@ Workflow:
 
 1. **Discover before composing.** `list_components` (`mode: "summary"` first),
    `get_theme`, `list_components` (`kind: "snippet"`), `list_boards`. Reuse existing snippets before
-   defining new ones.
+   defining new ones. When `get_theme` returns a `designSystem.path`, open that
+   file and read it: it is the folder's own design system in prose — house rules
+   that outrank the defaults below, and what the reviewer will check this work
+   against. Velloo points at the file rather than copying it, so it is current.
 2. **Build in big strokes.** `compose` accepts a full subtree as restricted
    JSX — a whole section per call, not node-by-node; `batch` groups mutations
    atomically. Repeated structure (cards, rows, nav items) becomes a snippet

package/skills/velloo-setup/SKILL.md

@@ -6,7 +6,8 @@ description: >-
   verify the canvas against the running app. Use once per repo before the first
   design task, and again when the app's design language changes. Triggers:
   "set up velloo for this repo", "make the preview match my app", "why doesn't
-  the canvas look like my app", or the setup step of an init handoff prompt.
+  the canvas look like my app", or before recreating an app's page from an
+  init handoff prompt.
 ---
 
 # Calibrating Velloo to an existing app
@@ -44,60 +45,23 @@ halfway through a design.
   tool re-probes and answers with the new state; iterate until `valid`.
 
 A snippet can't do this job: it is node data, so it can't import CSS, build a
-router or wrap the whole screen. Snippets are for step 4 below.
-
-## 1. Theme first — it buys the most
-
-`import_theme { cssPath, apply: true }` against the app's stylesheet. This is
-not just colors: it ingests `--radius`, `--font-*` roles, the non-semantic
-palette (`--primary-600`, `--ink`), and — when it finds a `tailwind.config`
-nearby — that config's `theme.extend` spacing, shadows, fonts, keyframes, and
-`container` settings. Run it dry first (the default) and read the reported
-changes; `apply: true` when they look like the app.
-
-Init records the stylesheet it found in the folder config, so check there
-before hunting. If there's no stylesheet (a `none`-CSS folder, an MUI app),
-`import_theme` still takes raw `css` text, and an MUI app's `createTheme` call
-is the equivalent source.
-
-**Fonts are the highest-leverage single token.** A design in the wrong typeface
-reads as wrong no matter how correct the layout is. If `import_theme` didn't
-resolve real families, set them with `set_theme { fonts }` — read the app's font loading
-(next/font, a `@font-face`, a Google Fonts link) to get the actual names.
-
-Then `score_theme_contrast` to confirm the imported palette holds up in both
-modes; an app that only ever ships light mode often imports into a dark palette
-that fails.
-
-## 2. Verify against the real thing, early
-
-Do not wait until a design is finished to discover the baseline was wrong.
-Recreate one representative screen — or use whatever init scaffolded — and run
-`compare_to_url` against the running app.
-
-- Get the app running first. Start its dev server yourself if the package
-  scripts make it obvious; otherwise ask the user for the command, a running
-  URL, or a deployed preview. Ask once, plainly, rather than guessing ports.
-- **Read `unverified` on every result.** `redirected` / `authWall` means you
-  captured a login page, so the similarity number is meaningless.
-- **For a login wall, use a capture session.** `start_capture_session { url }`
-  opens a real browser the *user* drives. It returns immediately — it does not
-  wait — so say plainly what you need ("log in, then hit **Capture page** in the
-  velloo toolbar on each page, then **Done**") and poll `list_captures` until
-  their captures land. Then verify with `compare_to_url { captureId }` instead
-  of `url`: the capture is already past the login and frozen, so it can't bounce
-  to a login page or drift between runs. `storageStatePath` / `cookies` /
-  `localStorage` stay available for when you already hold a session.
-- If you cannot get a real capture, **leave it unverified and say so.** Tuning a
-  design toward a page you never saw is worse than admitting the gap.
-- For a dashboard or feed whose content shifts between loads, pass
-  `cacheUrl: true` so you diff against one frozen capture instead of drifting
-  content.
+router or wrap the whole screen. Snippets are for step 3 below.
+
+## 1. Theme, fonts and the compare loop
 
-0.85+ similarity is a faithful structural port. Don't chase 1.0 — fonts and
-live data legitimately differ.
+The MCP instructions and `velloo://guide/porting` own this part: import the
+app's stylesheet with `import_theme` (dry run, then `apply: true`), set its real
+fonts with `set_theme { fonts }` — read how the app loads them; a wrong typeface
+makes a correct layout read as wrong — then recreate one representative screen
+and iterate `compare_to_url` against the running app, reading `unverified`
+before trusting any number. Two additions that live only here:
+
+- Run `score_theme_contrast` after the import. An app that only ever ships
+  light mode often imports into a dark palette that fails.
+- For a dashboard or feed whose content shifts between loads, pass
+  `cacheUrl: true` so you diff against one frozen capture.
 
-## 3. Establish component fidelity before adapting anything
+## 2. Establish component fidelity before adapting anything
 
 Only after theme parity, call `component_status { screen: "<id>" }` for each
 screen you're about to design or verify (or `{ ids: [...] }` before a screen
@@ -128,7 +92,7 @@ Host-source edits invalidate the canvas bundle automatically. After changing a
 component, wait for the frame to reload and call `component_status` again; do
 not restart the daemon merely to pick up a normal source edit.
 
-## 4. Close only the important remaining gaps
+## 3. Close only the important remaining gaps
 
 If an on-screen component is not `exact` and the difference is load-bearing,
 choose the smallest honest adaptation:
@@ -153,7 +117,7 @@ the adaptation is what keeps dialogs, menus, popovers, and similar components
 visible and selectable on a static canvas. Adapt only when the visual contract
 the user cares about is materially different.
 
-## 5. Leave a record
+## 4. Leave a record
 
 Write what you found as a note on the main board (`add_note`) so the next
 session — and the user — knows where things stand. Three headings, honest: