---
name: vizen-start
description: Entry point for building a Vizen shop through a personal API token — read the key passport, learn the map, and pick the right path BEFORE writing anything. Invoke first for any task touching /content-blocks, /html-documents, /design/bindings, categories or products. Question 0 — a finished site or export? — routes to a site folder or vizen-transfer, never to components; the rest to vizen-widgets, vizen-own-markup, vizen-chrome, vizen-catalog and vizen-troubleshoot.
---

# Start here

Your key's contour decides where writes go: production changes the live shop;
dev writes to a draft until publication. Read `writes_to_live` and warnings in
the passport first, then choose the task's path.

## 0. Have a finished site, folder or export? Stop here

A folder with `index.html`, a React/Vite build or a Figma/Webflow/Tilda export
exists: you are **transferring, not building**. Move it as it is. Do not cut it
into blocks or components unless you are asked to. Read the passport (§1), then:

| The owner wants | Path |
|---|---|
| the whole site on its own, byte for byte | **site folder**: category `type:"site"` → ZIP to `POST /site-folders/{id}/releases/zip?base=none&publish=1` → publish the category; `/docs/file-storage`. No shop header, cart or `vz-` keys inside; a dev key only leaves a draft |
| the site as the shop — live prices, cart, menu | `vizen-transfer`: one folder per page = a level-3 widget, plus layout and chrome |
| one page inside the shop | `vizen-transfer` §3 step 5: one folder = a level-3 widget on that page |
| a folder site or a section on `/` | `PUT /v1/home-page {"section_id":id}`, `/docs/file-storage` |

If it is unclear, ask the owner one question: a separate site as it is, or the
shop with live prices and cart. Do not choose for the owner.

## 0a. One page or the whole site? The layout decides

| What the owner wants | Where it goes |
|---|---|
| one page (landing, promo) | an html widget on that page — `--page <slug>` |
| something on **every** page: common CSS, fonts, `<head>`, a favicon, a script | the **LAYOUT's folder** — `--theme <id>`, `vizen-own-markup` §6.2 |
| header/footer for the whole site or for one section | groups bound to slots, on the shop, a section, or the layout — `vizen-chrome` |

Shared CSS goes in the layout folder: preview and guarded pages load it;
unbinding a header leaves it.

A layout is a group with `group_type:"theme"`; the default is the earliest by
id ("Основной"). `GET /content-blocks` has no filter — filter yourself. In the guarded zones (`/cart`,
`/checkout`, `/account`, `/wishlist`, `/orders`, `/coupons`, `/deals`, `/dashboard`) no
author script runs — layout code included; markup and styles stay.

## 1. Read the key passport

Read [Authentication](/docs/authentication), then `GET /v1/account/token`
before any write. Follow its `mode_guide` and pass warnings to the owner.
Public catalogue responses do not verify a key. Authentication owns the field
and error reference; do not infer permissions from a preset name.

Replacing a category grid: [family cards tutorial](/docs/guide-family-cards);
the canonical API sequence and rollback are `/docs/components` §4.8.

## 2. Ask three questions before the first write

**Trigger words: “unique”, “not like the rest”, “fully custom”.** Before writing,
resolve the forks below with the owner if the brief leaves them open (a wrong
route cost one run 12% of its steps). If the owner has already chosen, follow that choice; do not ask for approval again.

| Question | Path A | Path B |
|---|---|---|
| **Header, menu, footer** | platform widgets — fast, props/CSS restyling | own markup in an HTML block — your structure, needs a chrome group and binding |
| **"unique", "not like the rest"** | usually neither extreme: keep the widget and put your own class on its wrapper (`props.wrapperClass`), then restyle from your own CSS | own markup when the owner wants control of the structure or authoring |
| **Product lists** | platform `productListing` — filters, paging, sorting; props/CSS restyling | own markup — your structure and live prices (`vz-for="p in products"`); no built-in filters |
| **Product card** | change it for one product | change it for every product of a section — `category_children` inherits down the whole tree |
| **Needed more than once?** | one page — an html widget | many pages, different content — a **component** (`vizen-own-markup` §6.3): one folder, values per insertion |

Explain the real tradeoff: the own-markup feed has live prices but no built-in filter/sort controls; explicit picks: `/docs/own-markup` §2. Do not describe it as frozen data.

§6.2 and §6.3 are sections of the `vizen-own-markup` skill; in `/docs/own-markup`
the layout is [§7.2](/docs/own-markup#7-2-site-wide-css-and-js-live-in-the-layout-not-in-the-header),
components are [/docs/components](/docs/components).

## 3. Pick the skill

| The task is about | Skill |
|---|---|
| a finished site, folder, build or export to move as it is | §0: a site folder (`/docs/file-storage`) or `vizen-transfer` (`/docs/transfer`) |
| configuring platform blocks, their props and limits | `vizen-widgets` |
| own HTML/CSS/JS, vz- keys, modals, global CSS | `vizen-own-markup` |
| the same markup on many pages with different content | `vizen-own-markup` §6.3, area `GET /docs/components` |
| site-wide CSS/fonts/scripts, favicon, a second design for one section | `vizen-own-markup` (§6.2, the layout folder), `vizen-chrome` (§2a) |
| the cart, checkout, account pages — their header and footer | `vizen-chrome` §2a, system pages |
| making any block look unique — own class on the wrapper, or one wrapper axis | `vizen-own-markup` (§4), area `GET /docs/own-markup` §5 |
| header, menu, footer, layouts, second chrome kit | `vizen-chrome` |
| products, categories, filters, images, import, record sets; editorial pages and feeds (`GET /docs/news`) | `vizen-catalog` |
| prices, discounts, promo codes, combo sets | `vizen-catalog`, then `GET /docs/promotions` |
| forms, own quizzes, leads, CRM boards and webhook test modes | `GET /docs/forms`; `GET /docs/webhooks` |
| "I set it, got 200, nothing changed" | `vizen-troubleshoot` |
| closing the site while it is built (PIN, hidden from crawlers) | area `GET /docs/resource-access` |

## 4. Two rules that apply everywhere

**Look up before you write.** Field names, enum values and defaults come from
`GET /docs/widgets` and `GET /docs/vz-keys.json`, not from memory — both are
generated from the real code. Ask for one entry: `?kind=` and `?key=`.

**Validate before you write.** `POST /docs/validate` takes the exact `sections`
list you were about to PUT and answers per path: `applied`, `ignored`,
`unknown` or `unverified` (no schema — not a mistake). It writes nothing, so
there is no reason not to call it.

```
POST /docs/validate   {"sections":[ … ]}
```

Use it because the failures it catches are **silent**: a setting written beside
`kind` instead of under `props` is stored and renders nothing; a value outside an
enum is accepted and the default is drawn; `"12"` where a number belongs reads
back as the default. Every one of those answers 200.

**Verify by looking, not by status code.** Even after a clean validation, re-read
the object and open the page. The validator knows the schema; it does not know
whether the id you referenced exists or whether the result looks right.

## 5. Never

- print the token — not in answers, files, markup or reports;
- write to the cabinet, cart or checkout flows;
- use `git` at all: you work through the API only.