# Skládání nástěnek (https://docs.vitrinka.ai/cs/dev/compose) ## Karty v jedné dávce [#batch] Agent skládá jedním nástrojem, `compose_board`, jednu dávku na ucelený celek — sekci, přehled, srovnání — protože umístění i dráty se počítají per dávka; jediná karta je dávka o jedné. Dávka nese až šedesát karet, dráty mezi nimi a otázky, které chce nechat ukotvené ke kartě. Volání je všechno, nebo nic — při `400` chyba pojmenuje provinilou kartu indexem a nic se neumístilo — a poslední dávku jde vrátit jedním požadavkem, což je také jediné, čeho se undo agenta kdy dotkne; uživatelovo ⌘Z práci agenta nikdy nevrací. ```json { "board": "checkout-review", "layout": "row", "section": "Pass 3", "cards": [ { "ref": "summary", "kind": "prose", "payload": { "md": "Discount applied twice on the cart step." } }, { "ref": "table", "kind": "table", "payload": { "cols": [{ "key": "step", "label": "Step" }, { "key": "expected", "label": "Expected" }, { "key": "actual", "label": "Actual" }], "rows": [{ "step": "Cart", "expected": "-10%", "actual": "-20%" }] } } ], "edges": [ { "from": "summary", "to": "table" } ] } ``` ```http POST /api/v1/boards/checkout-review/undo ``` ## Bezpečné opakování [#retries] Každé logické operaci `compose_board` nebo `update_cards` přidělte unikátní `requestKey` (1–128 viditelných znaků ASCII). Přes HTTP lze stejnou hodnotu poslat v hlavičce `Idempotency-Key`. Stejný požadavek vrátí původní potvrzení bez dalšího vytváření či úprav, i po pozdějších změnách nebo restartu serveru. Použití stejného klíče s jiným vstupem vrátí `409`. Klíč patří ověřené identitě, nástěnce a operaci; nová operace potřebuje nový klíč. Šablona použije podobu z prvního úspěšného zápisu. Neplatné dávkové úpravy se vrátí zpět celé. ## Umístění vlastní server [#placement] Nic ve volání compose není souřadnice. Agent vyjádří záměr — `layout` (`column`, `row`, `grid`), `anchor` `{cardId | ref, relation}` na úrovni dávky nebo per karta (vlastní kotva karty přebíjí kotvu dávky a smí mířit na `ref` z téhož volání), `section`, do které má přistát, `journey` nebo `pass`, které má rozšířit — a server ho vyhodnotí. `after` a `before` vkládají v pořadí čtení uvnitř kontejneru kotvy, `under` je podpůrná řada pod ní (`after` uvnitř spravovaného rozložení), `beside` je soused vpravo, `into` připojí na konec rámu; potvrzení hlásí `placedAs` a `container` a nesplnitelný vztah je `400 relation_unsupported`, kdy se nic neumístí. Neukotvené dávky se rozkládají jako řady na polici. Později `arrange` přerozloží rozsah pojmenovaným režimem — mimo jiné `column`, `row`, `grid`, `flow`, `lanes`, `timeline`, `compare`, `journey` (strom zleva doprava řízený dráty nástěnky) a `graph` (strom dokumentů shora dolů řízený jejich dráty `ref`); na neznámý režim server odpoví celým seznamem — a se `save` to rozložení uloží na sekci, takže ho server dál přeskládává, jak karty přibývají. Pro `compose_board` používejte aktuální názvy druhů a režimů z reference. Neznámá hodnota se odmítne se seznamem povolených možností; u vyřazených názvů může chyba uvést náhradu. Pole `children` určuje pořadí obsahu uvnitř rámce nezávisle na pořadí definic v poli `cards`. Rodič a pořadí se ukládají nezávisle na naměřených rozměrech a vracejí se jako `placement: {parentId, order}`; rodič `0` označuje kořen. Nové rámce mají průběžně udržovanou dvousloupcovou mřížku, i když jsou zatím prázdné. `payload.layout: null` ponechá ruční umístění. `payload.layout` na rámci zachovává uspořádání do řádku, sloupce nebo mřížky při změnách obsahu. Parametr `layout` na úrovni celé dávky určuje její počáteční umístění. ## Přečíst, upravit, odebrat [#edit] Potvrzení dokazuje umístění, ne čitelnost: nástěnku si přečtěte zpátky přes `scrape_board` — jeden výtah karet s jejich sekcí, adresami médií, poznámkami, anotacemi, řetězy cest a otázkami; `section` vybere jeden rám — a řekněte, co jste nezkontrolovali. Element v AI vrstvě upravíte odkazem: `read_element {id}` vrátí osnovu s revizí a cestami JSON Pointer a `edit_element {id, revision, edits}` změní jen tyto cesty; `409` znamená přečíst znovu, nikdy slepě opakovat. `update_cards` upravuje vaše vlastní karty a rámy v AI vrstvě a je jedinými dveřmi pro odebrání. Odebrání je měkké — obnovitelné 30 dní: vlastní karty vyhodíte do koše volně, až 25 na volání a 30 % nástěnky; cizí karty nebo větší dávka odpoví `409 needs_confirm` — zopakujte stejná id s tokenem a důvodem. Ze shellu jsou tytéž dveře `vitrinka board cards rm --why "…"` — [nástěnky](/cs/dev/cli/boards#put). ## Jeden slovník, generovaný [#vocabulary] `kind` každé karty je uzavřený slovník generovaný z registru serveru: druhy karet nástěnky (`text`, `note`, `shape`, `callout`, `checklist`, `cluster`, `section`, `step`, `compare`, `doc`, `link`, `board`, `diagram`, `api`, `page`, `artifact`, `chat`) plus každý druh elementu. Tentýž seznam hlídá REST dveře, dveře elementů i schéma `compose_board`, takže obsah, který se složí na jedné instalaci, se složí na každé instalaci téže verze. Je vykreslený do [reference elementů](/cs/reference/elements) a živě ho servíruje nástroj `docs`. ## Nejdřív si přečtěte nástroj docs [#docs] MCP nástroj `docs` — a `vitrinka docs [topic]` z terminálu — je sjednocená reference téhle instalace, vrstvená kvůli úspoře tokenů: bez tématu vrátí kompaktní index každého druhu a průvodce; jedno téma vrátí jen tu stránku, s tvarem obsahu, příkladem a záludnostmi. Průvodci nástěnkou jsou `composing`, `organization`, `sections`, `uploads`, `recall`, `annotation`, `review`, `brief`, `tasks` a `project-transfer`; postupy, kterými se řídí skilly, jsou `guide:listening`, `guide:publish-capture`, `guide:brainstorm-flow` a `guide:sessions-pipeline`; `kind:` odpoví na druh generického slovesa; holé jméno druhu odpoví kontraktem elementu; stránky komponent kitu jsou `artifact:`. ```bash vitrinka docs # index vitrinka docs composing # rozložení, rámy, šablony, otázky vitrinka docs table # kontrakt jednoho elementu ``` ## Dokumenty se vnořují přes refy [#refs] Dokument se skládá z elementů. Element `ref`, například `{ "kind": "ref", "payload": { "card": 812, "mode": "preview" } }`, vloží jinou kartu, její náhled nebo odkaz (v odesílaném `doc.json` se tentýž blok píše naplocho a místo karty může jmenovat sesterskou `page` nebo `section` uvnitř dokumentu). Server propojí dokumenty vazbami `ref`; příkaz `arrange` v režimu `graph` z nich sestaví strom a samostatné zobrazení je využije pro osnovu. Při publikování `vitrinka board push` vytvoří stránky jako samostatné karty a převede odkazy `page:` na jejich ID — viz [sady](/cs/dev/cli/sets#docs). ## Společné vykreslování [#faces] Elementy používají společné vykreslování na nástěnce, v publikovaném dokumentu i samostatně na `/a/`. Pro snímek nebo tisk parametr `?press=1` odstraní vnitřní posouvání a ovládání zobrazované při najetí myší a načte média rovnou. `?theme=` přepíše uloženou předvolbu motivu. Toto zobrazení používá služba pro pořizování snímků a tentýž vykreslovač krmí i exporty: `GET /api/v1/boards/{slug}/cards/{id}.pdf`, `.eml` (koncept e-mailu s vloženými obrázky) a `.docx`, k tomu HTML z prohlížeče dokumentu. Element označený publikem `audience` — `public`, `technical`, `internal` — se zobrazí jen těmto čtenářům a `?audience=` stejně ořízne každý export. ## Šablony [#templates] `get_templates` vypíše vestavěné kostry — QA session, review iterace, mapa rozhodnutí, dashboard metrik, prezentace, třídění nálezů, návrh UI, mapa architektury, datový příběh, sada testovacích cest, stránka, importéry, dokumentační nástěnka, důkaz z chatu — a šablony z registru uložené přes `save_template` (nástroj modulu `rare`) — buď tělo ve tvaru compose se zástupnými `{{slot}}`, nebo živou sekci vytaženou jako kostru. `compose_board` s `template` a `params` jednu instanciuje a doporučený první tah na nové nástěnce je seznam jednou načíst a vyjít z odpovídající šablony. ## Otázky a review [#questions] Volání compose může nechat otázky ukotvené ke kartám (`ask_board` se zeptá samostatně). Člověk odpovídá na nástěnce — na brainstormové nástěnce v brainstormovém studiu — a odpovědi zůstanou odložené, dokud nestiskne **↑ Send**; pak dorazí jako položky s volbou na `wait_for_work`; `get {kind: "questions", board}` je trvalý záznam. AI review pass na serveru je `review_judge` (nástroj modulu `rare`): soudce a nezávislý auditor vytvoří rozsudky připnuté k verzi, které čtete přes `review_judgments`, a nic se na nástěnku automaticky nezaloží — založení rozsudku je výslovný krok, o kterém rozhoduje člověk. `request_review` zůstává jen jako kompatibilní název. `highlight` nakreslí na snímku anotace živý obdélník, který ukáže, co agent skutečně myslí.