# Create Vitruvio Panel (orchestrator)

> All messages shown to the user must be written in Portuguese.

A panel is one or two form files plus a manifest entry:

| Part | Skill that owns it |
|------|--------------------|
| `panels/<key>/<key>-desktop.xml` (web form) | **vitruvio-criar-form-desktop** (panel variant) |
| `panels/<key>/<key>-mobile.xml` (app form, optional) | **vitruvio-criar-form-mobile** (panel variant) |

This skill collects the intent once, drives those skills, and registers the panel in
`vitruvio.json`. Do the file work by following the referenced skills — do not re-derive
their templates here.

## Step 1 — Confirm you are inside a Vitruvio repo

```bash
ls vitruvio.json 2>/dev/null && echo "OK" || echo "NOT_A_VITRUVIO_REPO"
```

If `NOT_A_VITRUVIO_REPO`, stop and tell the user to `cd` into the correct repo.

## Step 2 — Collect panel details

Ask the user (in a single message, only ask what is missing):

- **Key** — PascalCase or snake_case unique identifier. Used in `engine.showPanel(key)` and
  as the folder name.
- **Name** — human-readable label shown in the Vitruvio menu.
- **Category** — display category, hierarchical with `/` (e.g. `"Comercial"`,
  `"Auditoria/Gondola"`).
- **Description** — one sentence (optional).
- **Open in new window?** — `true`/`false`. Default `true`.
- **Show in mobile list?** — `true`/`false`. Default `false`.
- **Needs a mobile form?** — if yes, a `<key>-mobile.xml` is created too. Mobile is a different
  schema with explicit data wiring (the mobile skill will ask for variables/lookups/libs).
- **What should the panel do?** — fields/behaviour, so the form scaffold is useful.

## Step 3 — Scaffold

```bash
vitruvio new panel <key> --name "<name>"
```

This creates `panels/<key>/<key>-desktop.xml` and the `vitruvio.json` entry. Then replace the
generated form using the focused skills:

1. **Desktop form** — follow **vitruvio-criar-form-desktop** (panel variant) to write
   `panels/<key>/<key>-desktop.xml` from the user's description.
2. **Mobile form (if requested)** — follow **vitruvio-criar-form-mobile** (panel variant) to
   write `panels/<key>/<key>-mobile.xml`. `vitruvio new` does not create it.

## Step 4 — Update vitruvio.json entry

`vitruvio new` already added the entry. Full shape:

```json
{
  "key": "<key>",
  "name": "<name>",
  "description": "<description>",
  "category": "<category>",
  "displayOrder": 0,
  "showInPresentation": false,
  "openInNewWindow": true,
  "showInMobileList": false,
  "displayTimeInSeconds": 0,
  "allowedGroups": [],
  "allowedUsers": [],
  "forms": {
    "desktop": "panels/<key>/<key>-desktop.xml"
  }
}
```

Fields `vitruvio new` typically leaves at defaults that need updating:
- `"category"` — set to the user's category (default `""`).
- `"description"` — add if provided.
- `"openInNewWindow"` — set to `false` for same-window.
- `"showInMobileList"` — set to `true` for mobile visibility.
- If a mobile form was created, add `"mobile": "panels/<key>/<key>-mobile.xml"` inside `"forms"`
  (and set `showInMobileList: true`).

## Step 5 — Report

Tell the user:
- Files created: `<key>-desktop.xml` (and `<key>-mobile.xml` if applicable).
- Registered in `vitruvio.json` with key `<key>`.
- `run()` in `<initScript>` is called every time the panel opens.
- `${paramName}` for SQL substitution in datasource blocks; `:paramName` only in named query files.
- For mobile: only explicitly declared data is available on the device — see vitruvio-criar-form-mobile.