<a name="english"></a>

<p align="center"><img src="design/icon/kuips-icon.svg" width="128" alt="KUIPS icon: a grey wireframe phone, a short chevron, a glowing pink phone"></p>

<h2 align="center">KUIPS</h2>

<p align="center">
  <a href="#english"><img src="https://img.shields.io/badge/English-2C7BE5?style=for-the-badge" alt="English"></a>
  &nbsp;
  <a href="#russian"><img src="https://img.shields.io/badge/Русский-C0392B?style=for-the-badge" alt="Русский"></a>
</p>

<p align="center"><b>Krinik User Interface Prototyping System</b><br>
A local Figma-like sheet where AI agents lay out an app's screens and the wiring between them</p>

<p align="center">
  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"></a>
  <a href="CHANGELOG.md"><img src="https://img.shields.io/badge/version-1.3.0-FF1A8C.svg" alt="version 1.3.0"></a>
  <a href="#en-5"><img src="https://img.shields.io/badge/MCP-2026--07--28_and_legacy-6A5ACD.svg" alt="MCP 2026-07-28 and legacy"></a>
  <a href="#en-4"><img src="https://img.shields.io/badge/CLI-kuips-0EA5E9.svg" alt="CLI: kuips"></a>
  <a href="#en-2"><img src="https://img.shields.io/badge/Node.js-%E2%89%A518-3DDC84.svg" alt="Node.js 18 or newer"></a>
  <a href="https://github.com/MikalaiKryvusha/KAIF"><img src="https://img.shields.io/badge/framework-KAIF-7F52FF.svg" alt="framework: KAIF"></a>
</p>

[Читать по-русски →](#russian)

**KUIPS** puts every screen of an app on one sheet and draws how they connect: which button leads where, which
process a screen belongs to, which states hide behind a tap. An AI agent describes the screens and the links in a JSON
manifest and captures the screen images with `kuips shoot` — from the live app or from HTML mock-ups. KUIPS then builds
one HTML file: colour connector lines (pipes) with direction arrows, screens grouped into named sections by process, a
component library and the design tokens read from the app's own styles. The file opens with a double click — no
server, no account, no internet. You move around the sheet the way you do in Figma: the wheel scrolls or zooms at your choice,
Ctrl+wheel and a pinch zoom, Space + drag pans, Shift+1 fits the whole sheet, Ctrl+\ hides the interface. A KUIPS icon on the desktop opens
the home page in your browser: one tile for every project whose sheet you built, a click opens its sheets.

<p align="center">
  <img src="docs/images/sheet-row.webp" width="100%" alt="A row of the Brewlog example: phone screens, a 390 × 860 px phone screen and a landscape timer, wired by colour pipes inside a framed row">
</p>
<p align="center">
  <img src="docs/images/zoom-menu.webp" width="49%" alt="The zoom menu opened from the zoom level at the top right: Wheel zooms, Fit the whole sheet, 25 % to 200 %; the left panel lists the sheets and the sections">
  <img src="docs/images/panels-folded.webp" width="49%" alt="Every panel folded: the whole sheet on screen and small chevron tabs at the screen edges that bring the panels back">
</p>
<p align="center">
  <img src="docs/images/cards-closeup.webp" width="49%" alt="Close-up: screen cards with name and address on top, the frame, and a note with the paths out and in below">
  <img src="docs/images/components.webp" width="49%" alt="The Components page: atoms, molecules and organisms cropped from the mock-ups">
</p>
<p align="center">
  <img src="docs/images/home.webp" width="49%" alt="The KUIPS home page: the KUIPS icon, project search and a tile of the Brewlog example with three screens as its cover, its description, the number of sheets and the date of the last change">
  <img src="docs/images/wayback.webp" width="49%" alt="The sheet dragged away from its screens: an arrow in the accent colour at the window edge points back to them with the distance in pixels, and hovering it shows Back to the sheet">
</p>

Sections: [1 What it does](#en-1) · [2 Quick start](#en-2) · [3 The manifest](#en-3) · [4 Commands](#en-4) ·
[5 For AI agents: CLI, API, MCP](#en-5) · [6 Checking the sheet](#en-6) · [7 Project map](#en-7) ·
[8 History](#en-8) · [9 Credits and licence](#en-9).

<a name="en-1"></a>
### 1. What it does

1. Lays screens out by a rule: a row is a process, a column is a step of the user's path, a tier above or below holds
   alternative states. The agent writes the table of rows; KUIPS computes the coordinates. On the sheet every row is a
   named **section**, as in Figma: a coloured frame around its screens with the row's name on a plate.
2. Draws links as pipes, the way a plumber would: right angles, rounded turns, one colour per source screen, parallel
   lanes in shared corridors, a direction triangle every 300 px of the sheet. Labels find a free place by themselves and
   never overlap a pipe, a screen or another label.
3. Puts every screen in a card: name and address on top, the screen image in the middle, a note below with the paths out
   (→) and in (←); a screen with no way out says so in its note.
4. Takes screens of any size on one sheet: phones of 390 × 900 px and 390 × 860 px, landscape 860 × 390 px, tablets. A
   column is as wide as its widest screen; a screen image is never cropped.
5. Captures the screen images itself with Playwright: from a live app (an address, a selector to wait for, clicks and
   typing for states that have no address) or from an HTML mock-up page (one element per screen). Images are WebP by
   default. When an error page opens instead of the screen, or the app quietly redirects elsewhere, `kuips shoot` skips
   the image and reports it — a wrong image never appears under a screen's name. A screen drawn small inside a frame,
   such as a phone next to a TV on one mock-up, is shot once more at the pixel density of its own interface; the sheet
   lays this sharp insert over the frame when you zoom in on the frame. The sheet redraws in the pauses of a zoom or a scroll, so
   the gesture itself stays smooth.
6. Builds the **Components** and **Design tokens** sheets from the real product: components are cut-outs of real
   elements grouped by Atomic Design (atoms, molecules, organisms), tokens are read from computed styles with a column
   per theme: the light and the dark theme, or the project's own themes by name. A token that refers to another one
   shows the name it refers to, like a variable alias in Figma. Both sheets open on the canvas of the flow map and move
   like it.
7. Keeps the zoom and the gear menu together at the top right of the sheet: zoom out, the zoom level, zoom in, fit,
   then the gear with **Settings** (accent colour, theme, interface language: English or Russian, the crosshair and
   every shortcut of the sheet), **Project** (the number of screens, links and sections, when the project and the sheet
   were created (from git), when the project last changed and when the sheet was last built) and **About** (KUIPS version, its build number and build date). A click on
   the zoom level opens the zoom menu: **Wheel zooms**, fit the whole sheet (Shift+1), 25 % to 200 % in steps of 25 %
   (100 % is Shift+0).
8. Lets you select text with the mouse. Press on text and drag to select it; press on empty space and drag to move the
   sheet. The cursor shows which of the two will happen. Double-click selects a word, Ctrl+C copies. Screen names,
   addresses, notes, link labels, row titles — and the text inside the screen images: `kuips shoot` records every line
   of text of a mock-up with its position, and the sheet lays an invisible, selectable copy of it over the image.
9. Moves and zooms the sheet the way Figma does. The wheel scrolls the sheet up and down, Shift+wheel scrolls it
   sideways, two fingers on a trackpad move it in any direction. Ctrl+wheel (⌘+wheel on a Mac) and a trackpad pinch
   zoom to the pointer. **Wheel zooms** in the zoom menu, or a middle click, makes the plain wheel zoom too; holding the
   middle button and moving the mouse up or down zooms to the point you pressed. The wheel over the zoom level changes
   it by 1 % a notch. Space + drag moves the sheet even over text. Shift+1 fits the whole sheet. Shift+2 brings the
   sheet to the section chosen last in the left panel (on a fresh sheet, to the first section). The section under the
   centre of the work area is highlighted, and its name follows the sheet's name in the title; **Crosshair** in Settings
   marks that centre with a dot. Shift+=
   and Shift+− zoom in and out. The sheet keeps its screens near: they can leave the window by at most half a window.
   When no screen is in the window, an arrow in the accent colour at its edge points to the centre of the screens and shows the distance
   in pixels; hovering it shows **Back to the sheet**, a click fits the whole sheet, and the arrow fades once a screen is
   back in view.
10. Folds the panels so they do not cover the sheet. The chevron button "‹" in the left corner of a left panel folds it
    to the left edge of the screen, and a small tab with a chevron stays at that edge, next to where the button was. A
    click on the tab brings the panel back. The top-right panel with the zoom and the gear folds the same way to the
    right edge, by its chevron button "›" on its right side. Ctrl+Shift+\
    folds all panels, and pressing Ctrl+Shift+\ again unfolds them. Ctrl+\ hides the whole interface, and pressing
    Ctrl+\ again or Esc brings the interface back.
11. Links several sheets of one project. List them in the manifest (`layers`), and the **Sheets** panel on the left of
    every sheet shows them all, the current one highlighted, followed by **Components** and **Design tokens**; a click
    opens the neighbour sheet, straight from the disk. Under
    the sheets, the left panel lists the sections of the sheet when the open sheet has any; a click on a section brings
    it into view. Many sheets and sections make the panel's list scroll.
12. Gives your projects a home. `npx kuips shortcut` puts a KUIPS icon on the desktop (Windows). A click starts KUIPS as an
    icon in the tray and opens the home page in your default browser: one tile for every project
    whose sheet you built — a cover of its first screens, its logo, name and description, the number of screens and
    the date the sheet was built. A click on a tile opens the project's sheets; **Settings → KUIPS home** on a sheet
    brings you back. A project appears on the home page by itself after `kuips build`; an open home page shows the
    new tile by itself. The tray menu opens the home page or quits KUIPS.
13. Checks the sheet with one command and names every defect by class (section 6).

<a name="en-2"></a>
### 2. Quick start

Install KUIPS into the project, and Chromium, the browser KUIPS captures screens with:

```bash
npm install --save-dev github:MikalaiKryvusha/KUIPS#v1.3.0
npx playwright install chromium
```

Create the manifest, describe the screens in it (section 3), then capture the images, lay the screens out, build and
check the sheet:

```bash
npx kuips init --lang en          # design/flow-map/flow-map.json
npx kuips shoot                   # frames → design/flow-map/screens/*.webp
npx kuips layout                  # coordinates from the table of rows
npx kuips build                   # design/flow-map.html
npx kuips check                   # 0 defects
```

Put KUIPS on the desktop once — the icon opens the home page with every project you build:

```bash
npx kuips shortcut                # Windows: KUIPS.lnk on the desktop, KUIPS in the tray
```

The `examples/brewlog` folder holds a complete example: an HTML mock-up page, the manifest and the built sheet. Open
`examples/brewlog/design/flow-map.html` in a browser to see it.

<a name="en-3"></a>
### 3. The manifest

The manifest `design/flow-map/flow-map.json` is the single source of the sheet. KUIPS builds `design/flow-map.html` from
it: edit the manifest and rebuild, never edit the HTML by hand. The keys are English. KUIPS does not build a sheet from a
manifest of KUIPS 0.9–1.2 with Russian keys and names the command that converts it, `npx kuips migrate`.

```json
{
  "title": "Brewlog — screens and flows",
  "lang": "en",
  "screen": { "width": 390, "height": 900 },
  "shoot": { "base": "design/mockups.html", "format": "webp" },
  "screens": [
    { "id": "home", "name": "Home", "address": "tab: Home", "selector": "[data-screen=\"home\"]",
      "note": "Week stats and recent brews" },
    { "id": "timer", "name": "Brew timer", "selector": "[data-screen=\"timer\"]", "width": 860, "height": 390 }
  ],
  "links": [{ "from": "home", "to": "timer", "label": "Start" }],
  "layout": [{ "name": "Brewing", "places": [["home", 0, 0], ["timer", 1, 0]] }]
}
```

| Key | What it holds |
|---|---|
| `title`, `subtitle` | the sheet's heading; `subtitle` opens under **Description** |
| `project` | the project's name; when set, the heading reads "Project: Sheet" (`project`: `title`) |
| `description`, `cover`, `logo` | the project's tile on the home page: what the project is, a cover image and a logo (paths from the project root); without them the tile shows the first screens and the first letter of the name |
| `lang` | interface language of the sheet: `en` or `ru` |
| `screen` | default screen size, `{ width, height }` |
| `screens[]` | `id`, `name`, `address`, `file`, `note`, `width`, `height`, `x`, `y`; for the shooter `wait`, `selector`, `steps`, `pause`, `errorOk`, `redirectOk`, `details` |
| `links[]` | `from`, `to`, `label` |
| `layout[]` | rows: `name`, `places: [[id, column, tier], …]` |
| `shoot` | `base` (app URL or mock-up page), `format`, `scale`, `locale`, `storage`, `theme`, `out`, `details` (`false` — no sharp inserts) |
| `library` | `components[]`: `id`, `name`, `layer`, `selector`, `address`; `schemeAddress`; `themes[]`: `id`, `name`, `class`; `themeTarget` |
| `layers[]` | the project's sheets for the **Sheets** panel: `title`, `path` — the sheet's HTML file, from the project root |
| `rows[]`, `sheet` | written by `kuips layout` |

A project with several sheets — say, accepted screens, screens under review and rejected ones — puts the same `layers`
list into each sheet's manifest:

```json
"layers": [
  { "title": "Accepted", "path": "design/flow-map.html" },
  { "title": "Under review", "path": "design/flow-map-review.html" },
  { "title": "Rejected", "path": "design/flow-map-rejected.html" }
]
```

Next to every frame `kuips shoot` writes its text layer, `screens/home.webp` → `screens/home.text.json`: the size of
the captured element and its lines of text, `{ "x", "y", "w", "h", "size", "text" }` in CSS pixels. A frame without
this file is shown without selectable text.

A screen drawn small inside a frame gets sharp inserts: `screens/devices.webp` → `screens/devices.detail-1.webp` and
the list `screens/devices.details.json`. On a screen shot from a mock-up page by its `selector`, `kuips shoot` finds
every element at least 120 × 60 px drawn at half of its own width or smaller
(a whole interface shrunk by a CSS transform) and shoots it at the density of that interface. The sheet loads an insert
in a pause, when the insert is in view and the frame on screen is larger than its natural size. `"details": false` on
a screen or in `shoot` turns the inserts off. Screen images and components are WebP unless `shoot.format` says `png`;
the inserts are always WebP.

Design tokens by theme. A project whose themes are CSS classes names them in `library.themes`. For each theme
`kuips library` puts its class on `<html>`, or on the element of `library.themeTarget`, and reads the variables
there; the **Design tokens** sheet gets a column per theme:

```json
"library": {
  "schemeAddress": "design/mockups.html",
  "themes": [
    { "id": "mana", "name": "Mana", "class": "th-mana" },
    { "id": "gold", "name": "Gold", "class": "th-gold" }
  ]
}
```

A variable whose rule says `var(--x)` shows `→ --x` under its value. When a mock-up page is opened from disk,
`kuips library` also reads the variables of the CSS files linked to it; a CSS file it cannot read and a theme class that
no CSS rule uses are named in its output. Without `themes` the sheet shows the light and the dark theme.

<a name="en-4"></a>
### 4. Commands

| Command | What it does |
|---|---|
| `kuips init [--lang en\|ru] [--title T]` | creates the manifest skeleton |
| `kuips shoot [--base URL] [--only id,…]` | shoots the frames of the screens and their text layers |
| `kuips library [--base URL]` | shoots the components and reads the design scheme |
| `kuips layout` | computes coordinates from the table of rows |
| `kuips build [--no-home]` | builds the sheet and puts the project on the home page (`--no-home` — without it) |
| `kuips register [--description T]` | puts a sheet built earlier on the home page; `T` — what the project is, for its tile |
| `kuips home [--port N] [--open]` | starts KUIPS with the home page at `http://127.0.0.1:4747/` |
| `kuips shortcut` | puts the KUIPS icon on the desktop: KUIPS in the tray, the home page in the browser (Windows) |
| `kuips check [--max-age-days N]` | checks the sheet |
| `kuips migrate [--registry] [--dry-run]` | converts a manifest and a library of KUIPS 0.9–1.2 to the English keys; `--registry` converts the home page registry too |
| `kuips mcp` | starts the MCP server on stdio |
| `kuips version` | prints the version, the build number and the build date |

Every command takes `--root DIR` (the project root), `--manifest P` (the manifest path, relative to the root) and
`--json`. Exit codes: 0 — done, 1 — defects or errors, 2 — wrong call. The CLI speaks Russian by default;
`KUIPS_LANG=en` switches its messages to English.

<a name="en-5"></a>
### 5. For AI agents: CLI, API, MCP

**CLI.** `--json` prints a machine-readable result with stable English keys:

```bash
npx kuips check --json
# { "command": "check", "ok": true, "defects": [], "warnings": [], "summary": { "screens": 8, "links": 9, … } }
```

**API.** The CLI's functions can be imported from the `kuips` package:

```js
import { build, layout, check } from 'kuips';
const r = check({ root: process.cwd() });
if (!r.ok) console.log(r.defects);
```

**MCP.** `kuips mcp` serves six tools — `kuips_build`, `kuips_check`, `kuips_layout`, `kuips_screens`, `kuips_shoot`,
`kuips_crop` — to clients of MCP revision 2026-07-28 (`server/discover`, per-request `_meta`) and of the earlier
revisions (`initialize`). `kuips_crop` returns a PNG of one screen card or one row, so the agent shows a person exactly
the place under discussion. To connect Claude Code, put this `.mcp.json` into the project root:

```json
{ "mcpServers": { "kuips": { "command": "node", "args": ["node_modules/kuips/bin/kuips.mjs", "mcp"] } } }
```

<a name="en-6"></a>
### 6. Checking the sheet

`kuips check` reads the same geometry the sheet draws and reports each defect with a class code:

| Class | What it looks like on the sheet |
|---|---|
| `pipe-through-card` | a pipe crossing a screen |
| `pipe-off-border` | a pipe that starts or ends in the air next to a screen |
| `triangle-under-card` | a direction arrow hidden under a screen |
| `label-overlap` | a label lying on a pipe, a screen or another label |
| `shelf-on-frame` | a pipe running along the frame of a row |
| `missing-frame` | a screen without its frame |
| `aspect-mismatch` | a frame whose proportions differ from the screen size |
| `external-link` | a sheet that needs the internet |
| `sheet-stale` | a sheet built before the last change of the manifest or the frames |
| `frames-old` | frames older than `--max-age-days` |

Warnings do not fail the check: `frame-unused` (an image no screen uses), `sheet-missing` (the sheet is not built),
`text-layer-missing` (a frame without its text layer: its text cannot be selected — `kuips shoot` captures it),
`layer-missing` (a sheet listed in `layers` is not built yet).

<a name="en-7"></a>
### 7. Project map

```
bin/kuips.mjs          the CLI
src/index.mjs          the API
src/manifest.mjs       the manifest and its validation
src/migrate.mjs        kuips migrate: files of KUIPS 0.9–1.2 → English keys
src/locales/           the texts of KUIPS in en and ru and the sizes that depend on the language
src/geometry.mjs       pipes, lanes, direction triangles, label placement
src/layout.mjs         the table of rows → coordinates
src/sheet.mjs          the HTML sheet, the gear menu, the pages
src/sheet/             the sheet's styles and its viewer, one module per part
src/home/              the home page, the project registry, the tray and the desktop icon
src/check.mjs          kuips check
src/shoot.mjs          the screen and library shooters
src/mcp.mjs            the MCP server
examples/brewlog/      a complete example
test/                  node:test units; the shooter and render tests drive a real Chromium
```

<a name="en-8"></a>
### 8. History

KUIPS was born on 4 September 2026. Mikalai Kryvusha asked for one page where he could see a whole app from above —
screens side by side, arrows between them, the way designers do it in Figma, but open and local. The next day the sheet
got pipes, rows, pages, the component library and the name KUIPS. On 16 October 2026 KUIPS moved into its own
repository as version 0.9.0; version 1.0.0 works in any project. Version 1.1.0, on 20 October 2026, moves around the
sheet the way Figma does: selectable text, a zoom menu, Figma keys, named sections and panels that fold into edge
tabs. Version 1.2.0, on 21 October 2026, gives the projects a home page behind a desktop icon, and the sheet keeps its
screens in reach with a blue arrow back. Version 1.3.0, on 22 October 2026, lets the wheel zoom, opens the library as
sheets on the canvas, moves every text into locale files and takes the manifest's English keys only. Version 1.3.1, on
23 October 2026, shows the design tokens by the project's own themes with their aliases, lays sharp inserts over screens
drawn small inside a frame and redraws the sheet in the pauses of a zoom. The changes are in
[CHANGELOG.md](CHANGELOG.md).

<a name="en-9"></a>
### 9. Credits and licence

MIT © 2026 Mikalai Kryvusha (KOT KRINIK). Frames are shot with [Playwright](https://playwright.dev) (Apache-2.0). The
project is run with [KAIF](https://github.com/MikalaiKryvusha/KAIF), the author's framework for work with AI agents.

---

<a name="russian"></a>

<p align="center"><img src="design/icon/kuips-icon.svg" width="128" alt="Иконка KUIPS: серый телефон-набросок, короткий шеврон, светящийся розовый телефон"></p>

<h2 align="center">KUIPS</h2>

<p align="center">
  <a href="#english"><img src="https://img.shields.io/badge/English-2C7BE5?style=for-the-badge" alt="English"></a>
  &nbsp;
  <a href="#russian"><img src="https://img.shields.io/badge/Русский-C0392B?style=for-the-badge" alt="Русский"></a>
</p>

<p align="center"><b>Krinik User Interface Prototyping System</b><br>
Локальная «фигма» для ИИ-агентов: экраны приложения и связи между ними на одном листе</p>

[Read in English →](#english)

**KUIPS** кладёт все экраны приложения на один лист и рисует, как они связаны: какая кнопка куда ведёт, к какому
процессу относится экран, какие состояния прячутся за нажатием. ИИ-агент описывает экраны и связи в манифесте JSON и
снимает кадры экранов командой `kuips shoot` — с живого приложения или с HTML-макетов. Из манифеста и кадров KUIPS
собирает один HTML-файл: цветные линии связей (трубы) со стрелками направления, экраны в именованных секциях по
процессам, библиотека компонентов и дизайн-схема, прочитанная из стилей самого приложения. Файл открывается двойным
щелчком, без сервера, без учётной записи и без интернета. По листу ходят, как в Figma: колесо прокручивает или масштабирует —
на ваш выбор, Ctrl+колесо и щипок масштабируют, пробел + перетаскивание двигает лист, Shift+1 вписывает весь лист, Ctrl+\ прячет интерфейс. Иконка
KUIPS на рабочем столе открывает в браузере домашнюю страницу: плитка на каждый проект, у которого собран лист, щелчок
открывает его листы.

<p align="center">
  <img src="docs/images/sheet-row.webp" width="100%" alt="Ряд примера Brewlog: экраны телефона, экран 390 × 860 пикселей и таймер в альбомной ориентации, связанные цветными трубами внутри рамки ряда">
</p>
<p align="center">
  <img src="docs/images/zoom-menu.webp" width="49%" alt="Меню масштаба: «Колесо масштабирует», «Вписать весь лист», от 25 % до 200 %">
  <img src="docs/images/menu-settings.webp" width="49%" alt="Меню-шестерёнка, «Настройки»: цвет, тема, язык надписей, прицел и все клавиши листа">
</p>
<p align="center">
  <img src="docs/images/menu-about.webp" width="49%" alt="Меню-шестерёнка, вкладка «О приложении»: версия, номер и дата сборки, лицензия, автор и репозиторий">
  <img src="docs/images/cards-closeup.webp" width="49%" alt="Карточки экранов крупно: имя и адрес сверху, кадр, внизу заметка и пути">
</p>
<p align="center">
  <img src="docs/images/home.webp" width="49%" alt="Домашняя страница KUIPS: иконка KUIPS, поиск проекта и плитка примера Brewlog — три экрана на обложке, описание, число листов и дата последнего изменения">
  <img src="docs/images/wayback.webp" width="49%" alt="Лист утащен от экранов: стрелка цвета акцента у края окна показывает обратную дорогу и расстояние в пикселях, при наведении — подсказка «Вернуться к листу»">
</p>

Разделы: [1 Что умеет](#ru-1) · [2 Быстрый старт](#ru-2) · [3 Манифест](#ru-3) · [4 Команды](#ru-4) ·
[5 Для ИИ-агентов: CLI, API, MCP](#ru-5) · [6 Проверка листа](#ru-6) · [7 Карта проекта](#ru-7) ·
[8 История](#ru-8) · [9 Благодарности и лицензия](#ru-9).

<a name="ru-1"></a>
### 1. Что умеет

1. Раскладывает экраны по правилу: ряд — это процесс, колонка — шаг пути пользователя, ярус над или под экраном — его
   альтернативное состояние. Агент пишет таблицу рядов, координаты считает KUIPS. На листе каждый ряд — именованная
   **секция**, как в Figma: цветная рамка вокруг его экранов и плашка с именем ряда.
2. Рисует связи трубами, как водопровод: прямые углы, скруглённые повороты, свой цвет у каждого экрана-источника,
   параллельные полосы в общих коридорах, треугольник направления каждые 300 пикселей листа. Подпись связи сама
   находит свободное место и не ложится на трубу, экран или другую подпись.
3. Кладёт каждый экран в карточку: сверху имя и адрес, посередине кадр, внизу заметка и пути «→ куда ведёт» и
   «← откуда приходят». Если у экрана нет путей наружу, заметка говорит об этом словами.
4. Держит на одном листе экраны любого размера: телефоны 390 × 900 и 390 × 860 пикселей, альбомные 860 × 390,
   планшеты. Ширина колонки равна ширине самого широкого экрана в ней; кадр не обрезается.
5. Снимает кадры сам, через Playwright: с живого приложения (адрес, селектор элемента, которого съёмщик ждёт, клики и
   ввод для состояний без адреса) или со страницы HTML-макетов (один элемент на экран). Кадры по умолчанию в WebP.
   Если вместо экрана открылась страница ошибки или приложение незаметно ушло на другой адрес, `kuips shoot` такой
   кадр не снимает и называет экран: чужой кадр под именем экрана не окажется. Экран, нарисованный внутри кадра
   маленьким, например, телефон рядом с телевизором на одном макете, снимается ещё раз с плотностью его собственного
   интерфейса; лист кладёт эту чёткую вставку поверх кадра, когда вы его приближаете. Во время масштабирования и
   прокрутки лист двигает готовую картинку и перерисовывается в паузе: жест идёт плавно.
6. Собирает листы **Компоненты** и **Дизайн-схема** с живого приложения: компоненты — вырезки настоящих элементов,
   разложенные по Atomic Design (атомы, молекулы, организмы); токены прочитаны из вычисленных стилей, колонка на каждую
   тему: светлая и тёмная или темы проекта по именам. Под значением токена-ссылки стоит имя токена, на который он
   ссылается, как у псевдонима переменной в Figma. Оба листа открываются на полотне развёртки и двигаются, как развёртка.
7. Справа вверху листа — масштаб и меню-шестерёнка рядом: отдалить, масштаб в процентах, приблизить, вписать, и
   шестерёнка с **Настройками** (цвет акцента, тема, язык надписей: русский или английский, прицел и все клавиши листа),
   **Проектом** (число экранов, связей и секций; когда созданы проект и лист (по git), когда проект изменён последний раз и когда лист собран последний раз) и **О приложении** (версия
   KUIPS, номер и дата её сборки). Щелчок по проценту масштаба открывает меню масштаба: **Колесо масштабирует**, вписать
   весь лист (Shift+1), от 25 % до 200 % шагом 25 % (100 % — Shift+0).
8. Даёт выделять текст мышью. Зажали на тексте и повели — текст выделяется; зажали на пустом месте — лист едет за
   мышью. Курсор заранее показывает, что будет. Двойной щелчок выделяет слово, Ctrl+C копирует. Выделяется всё: имена
   и адреса экранов, заметки, подписи связей, имена рядов — и текст внутри кадров: `kuips shoot` записывает каждую
   строку текста макета с её местом, а лист кладёт поверх кадра её невидимую копию, которую можно выделить.
9. Двигает и масштабирует лист, как Figma. Колесо прокручивает лист вверх-вниз, Shift+колесо — вбок, два пальца по
   тачпаду двигают лист в любую сторону. Ctrl+колесо (на Mac ⌘+колесо) и щипок на тачпаде масштабируют к курсору.
   Пункт **Колесо масштабирует** в меню масштаба или щелчок средней кнопкой мыши переключает простое колесо на масштаб.
   Если зажать среднюю кнопку и вести мышь вверх или вниз, лист масштабируется к точке нажатия. Колесо над полем
   масштаба меняет масштаб на 1 % за шаг колеса.
   Пробел + перетаскивание двигает лист даже поверх текста. Shift+1 вписывает весь лист. Shift+2 подводит лист к
   секции, выбранной последней в панели слева (на новом листе — к первой секции). Секция в центре рабочей области
   подсвечена, её имя стоит в заголовке после имени листа; **Прицел** в «Настройках» ставит в этот центр точку. Shift+= и Shift+−
   приближают и отдаляют. Лист держит экраны рядом: они уходят за край окна не дальше чем на половину окна. Когда в окне
   нет ни одного экрана, у края окна горит стрелка цвета акцента к центру экранов с расстоянием в пикселях; при наведении на неё
   всплывает **Вернуться к листу**, щелчок вписывает весь лист, а стрелка плавно гаснет, как только экран вновь в окне.
10. Сворачивает панели, чтобы они не закрывали лист. Кнопка-шеврон «‹» в левом углу левой панели сворачивает её к
    левому краю экрана, у края остаётся маленький язычок с шевроном — там же, где была кнопка. Щелчок по язычку
    возвращает панель. Правая верхняя панель с масштабом и шестерёнкой сворачивается так же к правому краю, кнопкой-шевроном
    «›» справа. Ctrl+Shift+\ сворачивает все
    панели, повторное нажатие Ctrl+Shift+\ их разворачивает. Ctrl+\ прячет весь интерфейс, повторное нажатие Ctrl+\
    или Esc возвращает интерфейс.
11. Связывает несколько листов одного проекта. Перечислите их в манифесте (`layers`), и панель **Листы** слева на
    каждом листе покажет их все, текущий подсвечен, следом — **Компоненты** и **Дизайн-схема**; щелчок открывает соседний
    лист прямо с диска. Под листами панель слева
    перечисляет секции листа, если они есть на открытом листе; щелчок по секции подводит к ней лист. Когда листов и
    секций много, список в панели прокручивается.
12. Даёт проектам дом. `npx kuips shortcut` кладёт иконку KUIPS на рабочий стол (Windows). Щелчок запускает KUIPS
    значком в трее и открывает в браузере по умолчанию домашнюю страницу. На ней плитка на каждый проект с собранным листом:
    обложка из первых экранов, лого, имя и описание проекта, число экранов и дата сборки листа. Щелчок
    по плитке открывает листы проекта; **Настройки → Домашняя KUIPS** на листе возвращает на домашнюю. Проект
    появляется на домашней сам после `kuips build`, открытая домашняя сама показывает новую плитку. Меню значка в
    трее открывает домашнюю или закрывает KUIPS.
13. Проверяет лист одной командой и называет каждый дефект его классом (раздел 6).

<a name="ru-2"></a>
### 2. Быстрый старт

Установите в проект KUIPS и браузер Chromium, которым KUIPS снимает кадры:

```bash
npm install --save-dev github:MikalaiKryvusha/KUIPS#v1.3.0
npx playwright install chromium
```

Заведите манифест, опишите в нём экраны (раздел 3), затем снимите кадры, разложите экраны, соберите и проверьте лист:

```bash
npx kuips init                    # design/flow-map/flow-map.json
npx kuips shoot                   # кадры → design/flow-map/screens/*.webp
npx kuips layout                  # координаты по таблице рядов
npx kuips build                   # design/flow-map.html
npx kuips check                   # дефектов 0
```

Один раз положите KUIPS на рабочий стол — иконка открывает домашнюю со всеми проектами, которые вы собираете:

```bash
npx kuips shortcut                # Windows: KUIPS.lnk на рабочем столе, KUIPS в трее
```

Папка `examples/brewlog` — готовый пример: страница HTML-макетов, манифест и собранный лист. Откройте
`examples/brewlog/design/flow-map.html` в браузере.

<a name="ru-3"></a>
### 3. Манифест

Лист строится из манифеста `design/flow-map/flow-map.json`. Файл `design/flow-map.html` KUIPS собирает из манифеста:
правьте манифест и пересобирайте лист, HTML руками не правьте. Ключи манифеста английские. Лист по манифесту KUIPS 0.9–1.2
на русских ключах не собирается; KUIPS называет команду перевода `npx kuips migrate`.

```json
{
  "title": "Brewlog — экраны и переходы",
  "lang": "ru",
  "screen": { "width": 390, "height": 900 },
  "shoot": { "base": "design/mockups.html", "format": "webp" },
  "screens": [
    { "id": "home", "name": "Главная", "address": "вкладка «Главная»", "selector": "[data-screen=\"home\"]",
      "note": "Сводка недели и последние заварки" },
    { "id": "timer", "name": "Таймер", "selector": "[data-screen=\"timer\"]", "width": 860, "height": 390 }
  ],
  "links": [{ "from": "home", "to": "timer", "label": "Старт" }],
  "layout": [{ "name": "Заварка", "places": [["home", 0, 0], ["timer", 1, 0]] }]
}
```

Ключ `project` — название проекта: с ним заголовок листа читается «Проект: Лист», например «Brewlog: Экраны и переходы».
Ключ `subtitle` — подпись листа, она раскрывается под **Описанием**. Ключи `description`, `cover` и `logo` — плитка
проекта на домашней странице: суть проекта, картинка обложки и лого, пути от корня проекта; без них на обложке первые
экраны листа, на лого — первая буква имени. Таблица ключей — в [английской половине](#en-3). Адрес экрана, который начинается с `/`,
`?` или `#`, съёмщик открывает; адрес другого вида остаётся подписью на карточке.

У проекта может быть несколько листов: например, принятые экраны, экраны на согласовании и отклонённые. Тогда положите в
манифест каждого листа одинаковый список `layers`; путь к HTML листа считается от корня проекта:

```json
"layers": [
  { "title": "Принятое", "path": "design/flow-map.html" },
  { "title": "На согласовании", "path": "design/flow-map-review.html" },
  { "title": "Отклонённое", "path": "design/flow-map-rejected.html" }
]
```

Рядом с каждым кадром `kuips shoot` пишет его текстовый слой: `screens/home.webp` → `screens/home.text.json` — размер
снятого элемента и строки текста `{ "x", "y", "w", "h", "size", "text" }` в CSS-пикселях. Кадр без такого файла
показывается без выделяемого текста.

Экран, нарисованный внутри кадра маленьким, получает чёткие вставки: `screens/devices.webp` →
`screens/devices.detail-1.webp` и список `screens/devices.details.json`. На экране, снятом со страницы макетов по
`selector`, `kuips shoot` находит каждый элемент не меньше 120 × 60 пикселей,
нарисованный в половину своей ширины или мельче (целый интерфейс, уменьшенный CSS-трансформацией), и снимает его с
плотностью этого интерфейса. Лист загружает вставку в паузе, когда вставка в окне и кадр на экране крупнее своего
натурального размера. `"details": false` у экрана или в `shoot` выключает вставки. Кадры и компоненты KUIPS пишет в
WebP, если в `shoot.format` не стоит `png`; вставки всегда в WebP.

Дизайн-схема по темам. Проект, у которого темы — CSS-классы, называет их в `library.themes`. Для каждой темы
`kuips library` ставит её класс на `<html>` или на элемент из `library.themeTarget` и читает переменные там; лист
**Дизайн-схема** получает колонку на каждую тему:

```json
"library": {
  "schemeAddress": "design/mockups.html",
  "themes": [
    { "id": "mana", "name": "Мана", "class": "th-mana" },
    { "id": "gold", "name": "Золото", "class": "th-gold" }
  ]
}
```

Под значением переменной, у которой в правиле стоит `var(--x)`, лист пишет `→ --x`. Если страница макетов открыта с
диска, `kuips library` читает переменные и из подключённых к ней CSS-файлов; CSS-файл, который не удалось прочитать, и
класс темы, которого нет ни в одном правиле CSS, `kuips library` называет в выводе. Без `themes` лист показывает светлую и тёмную
тему.

<a name="ru-4"></a>
### 4. Команды

| Команда | Что делает |
|---|---|
| `kuips init [--lang ru\|en] [--title T]` | заводит заготовку манифеста |
| `kuips shoot [--base URL] [--only id,…]` | снимает кадры экранов и их текстовые слои |
| `kuips library [--base URL]` | снимает компоненты и читает дизайн-схему |
| `kuips layout` | считает координаты по таблице рядов |
| `kuips build [--no-home]` | собирает лист и ставит проект на домашнюю (`--no-home` — без этого) |
| `kuips register [--description T]` | ставит на домашнюю лист, собранный раньше; `T` — суть проекта для плитки |
| `kuips home [--port N] [--open]` | запускает KUIPS с домашней страницей `http://127.0.0.1:4747/` |
| `kuips shortcut` | кладёт иконку KUIPS на рабочий стол: KUIPS в трее, домашняя в браузере (Windows) |
| `kuips check [--max-age-days N]` | проверяет лист |
| `kuips migrate [--registry] [--dry-run]` | переводит манифест и библиотеку KUIPS 0.9–1.2 на английские ключи; `--registry` — и реестр домашней |
| `kuips mcp` | запускает MCP-сервер на stdio |
| `kuips version` | печатает версию, номер сборки и дату сборки |

У каждой команды есть `--root DIR` (корень проекта), `--manifest P` (путь к манифесту от корня) и `--json`. Коды возврата: 0 — готово, 1 — дефекты
или ошибки, 2 — неверный вызов. CLI по умолчанию говорит по-русски; `KUIPS_LANG=en` переключает его сообщения на английский.

<a name="ru-5"></a>
### 5. Для ИИ-агентов: CLI, API, MCP

**CLI.** `--json` печатает машиночитаемый результат с постоянными английскими ключами:

```bash
npx kuips check --json
# { "command": "check", "ok": true, "defects": [], "warnings": [], "summary": { "screens": 8, "links": 9, … } }
```

**API.** Функции CLI можно импортировать из пакета `kuips`:

```js
import { build, layout, check } from 'kuips';
const r = check({ root: process.cwd() });
if (!r.ok) console.log(r.defects);
```

**MCP.** `kuips mcp` отдаёт шесть инструментов — `kuips_build`, `kuips_check`, `kuips_layout`, `kuips_screens`,
`kuips_shoot`, `kuips_crop` — клиентам ревизии MCP 2026-07-28 (`server/discover`, `_meta` в каждом запросе) и более
ранних ревизий (`initialize`). `kuips_crop` возвращает PNG одной карточки экрана или одного ряда: агент показывает
человеку ровно то место, о котором разговор. Чтобы подключить Claude Code, положите в корень проекта файл `.mcp.json`:

```json
{ "mcpServers": { "kuips": { "command": "node", "args": ["node_modules/kuips/bin/kuips.mjs", "mcp"] } } }
```

<a name="ru-6"></a>
### 6. Проверка листа

`kuips check` читает ту геометрию, которую рисует лист, и называет каждый дефект кодом класса:

| Класс | Как это выглядит на листе |
|---|---|
| `pipe-through-card` | труба идёт сквозь экран |
| `pipe-off-border` | труба начинается или кончается в воздухе рядом с экраном |
| `triangle-under-card` | треугольник направления спрятан под экраном |
| `label-overlap` | подпись лежит на трубе, экране или другой подписи |
| `shelf-on-frame` | труба идёт вдоль рамки ряда |
| `missing-frame` | у экрана нет кадра |
| `aspect-mismatch` | пропорции кадра не совпадают с размером экрана |
| `external-link` | листу нужен интернет |
| `sheet-stale` | лист собран раньше последней правки манифеста или кадров |
| `frames-old` | кадры старше срока `--max-age-days` |

Предупреждения проверку не валят: `frame-unused` (картинка, которой не пользуется ни один экран), `sheet-missing` (лист
не собран), `text-layer-missing` (у кадра нет текстового слоя: его текст не выделяется — `kuips shoot` его снимет),
`layer-missing` (лист из списка `layers` ещё не собран).

<a name="ru-7"></a>
### 7. Карта проекта

```
bin/kuips.mjs          CLI
src/index.mjs          API
src/manifest.mjs       манифест и его проверка
src/migrate.mjs        kuips migrate: файлы KUIPS 0.9–1.2 → английские ключи
src/locales/           тексты KUIPS на ru и en и размеры, которые зависят от языка
src/geometry.mjs       трубы, полосы, треугольники направления, места подписей
src/layout.mjs         таблица рядов → координаты
src/sheet.mjs          HTML-лист, меню-шестерёнка, страницы
src/sheet/             стили листа и его просмотрщик, по модулю на часть
src/home/              домашняя страница, реестр проектов, трей и иконка на рабочем столе
src/check.mjs          kuips check
src/shoot.mjs          съёмщики экранов и библиотеки
src/mcp.mjs            MCP-сервер
examples/brewlog/      готовый пример
test/                  юниты node:test; тесты съёмщика и листа гоняют настоящий Chromium
```

<a name="ru-8"></a>
### 8. История

KUIPS родился 4 сентября 2026 года. Николай Кривуша попросил одну страницу, на которой видно всё приложение сверху:
экраны рядом, стрелки между ними, как у дизайнеров в Figma, но открыто и локально. На следующий день у листа появились
трубы, ряды, страницы, библиотека компонентов и имя KUIPS. 16 октября 2026 года KUIPS переехал в свой репозиторий с
версией 0.9.0. Версия 1.0.0 работает в любом проекте. Версия 1.1.0 от 20 октября 2026 года ходит по листу, как Figma:
выделение текста, меню масштаба, клавиши Figma, именованные секции и панели, которые сворачиваются в язычки у края
экрана. Версия 1.2.0 от 21 октября 2026 года даёт проектам домашнюю страницу за иконкой на рабочем столе, а лист держит
экраны рядом и показывает синей стрелкой обратную дорогу. Версия 1.3.0 от 22 октября 2026 года даёт колесу режим масштаба,
открывает библиотеку листами на полотне, выносит каждый текст в файлы локализации и принимает только английские ключи
манифеста. Версия 1.3.1 от 23 октября 2026 года показывает дизайн-схему по темам проекта с псевдонимами переменных, кладёт
чёткие вставки поверх экранов, нарисованных внутри кадра маленькими, и перерисовывает лист в паузах масштабирования.
Изменения — в [CHANGELOG.md](CHANGELOG.md).

<a name="ru-9"></a>
### 9. Благодарности и лицензия

MIT © 2026 Николай Кривуша (KOT KRINIK). Кадры снимает [Playwright](https://playwright.dev) (Apache-2.0). Проект ведётся
по [KAIF](https://github.com/MikalaiKryvusha/KAIF) — фреймворку автора для работы с ИИ-агентами.