jogos_matheus/.claude/skills/vitruvio-registrar-artefato/SKILL.md

---
name: vitruvio-registrar-artefato
description: >
  Use when the user has an existing file they want to add to a Vitruvio repository.
  Triggers: "I have an existing file", "move this to panels/", "register this artifact",
  "add this already existing", "tenho um arquivo pronto", "mover para o repo",
  or any request where the source file already exists and needs to be placed in the
  correct repo directory and registered in vitruvio.json.
  Do NOT use vitruvio-criar-* skills for this — those scaffold new files and would overwrite the existing one.
---

# Register Existing Artifact

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

You are wiring an already-existing file into a Vitruvio repository. No scaffolding — the file exists and must be placed correctly then registered in `vitruvio.json`. Follow these steps in order.

## 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 details

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

- **Source file path** — where the file currently lives (absolute or relative).
- **Artifact type** — one of: `panel`, `script`, `endpoint`, `query`, `report`, `library`, `process`.
- **Key** — kebab-case unique identifier for this artifact. Must be unique within its section in `vitruvio.json`. Changing it later is a breaking change.
- **Name** — human-readable label shown in the Vitruvio UI.
- Type-specific fields (only ask what is relevant):
  - Panel: `category` (e.g. `"Base de Conhecimento"`), `openInNewWindow` (default `true`), `showInMobileList` (default `false`), mobile form path if one also exists.
  - Script: `domain` — `USUARIO` (default) or `SISTEMA`.
  - Endpoint: `authMode` — `PUBLIC` (default), `STATIC_TOKEN`, `VITRUVIO_WS_USER_AUTH`, or `HTTP_BASIC_AUTH`.
  - Query: `connection` — datasource name (default `vitruvio_producao`).
  - Report: `type` — `MODELO_ESTATICO` or `DINAMICO_QUERY_SQL`; `query` key; `template` path; `parameterForm` path (optional).
  - Library: `authMode` — `PUBLIC` (default); `mobileEnabled` (default `false`).
  - Process: path to the BPMN file and desktop form XML if they are separate files.

## Step 3 — Place the file(s)

Create the destination directory if it does not exist, then move the source file to the correct location. **Never call `vitruvio new`** — it would scaffold and overwrite the existing file.

| Artifact | Destination | Notes |
|----------|-------------|-------|
| `panel` | `panels/<key>/<key>-desktop.xml` | Rename the source desktop form to `<key>-desktop.xml`. If a mobile form also exists, place it at `panels/<key>/<key>-mobile.xml`. |
| `script` | `scripts/<key>.js` | |
| `endpoint` | `endpoints/<key>.js` | |
| `query` | `queries/<key>.sql` | |
| `report` | `reports/<key>/` | Move jrxml and optional params.xml into this directory. |
| `library` | `libraries/<key>/` | Move all files into this directory. |
| `process` | `processes/<key>/` | Move the .bpmn and form XML(s) into this directory. |

```bash
# Example: panel
mkdir -p panels/<key>
mv /path/to/source.xml panels/<key>/<key>-desktop.xml
```

## Step 4 — Add entry to vitruvio.json

Read `vitruvio.json`. If the relevant section array does not exist, create it. Append the entry for the artifact type. Do **not** remove or modify any existing entries.

### Panel
```json
{
  "key": "<key>",
  "name": "<name>",
  "description": "<description or omit>",
  "category": "<category>",
  "displayOrder": 10,
  "showInPresentation": false,
  "openInNewWindow": true,
  "showInMobileList": false,
  "displayTimeInSeconds": 0,
  "allowedGroups": [],
  "allowedUsers": [],
  "forms": {
    "desktop": "panels/<key>/<key>-desktop.xml",
    "mobile": null,
    "mobileAlternative": null
  },
  "defaultState": null,
  "thumbnail": null
}
```

### Script
```json
{
  "key": "<key>",
  "name": "<name>",
  "description": "<description or omit>",
  "language": "javascript",
  "domain": "USUARIO",
  "source": "scripts/<key>.js"
}
```

### Endpoint
```json
{
  "key": "<key>",
  "name": "<name>",
  "description": "<description or omit>",
  "language": "javascript",
  "authMode": "PUBLIC",
  "active": true,
  "source": "endpoints/<key>.js"
}
```

### Query
```json
{
  "key": "<key>",
  "name": "<name>",
  "connection": "vitruvio_producao",
  "source": "queries/<key>.sql"
}
```

### Report
```json
{
  "key": "<key>",
  "name": "<name>",
  "description": "<description or omit>",
  "type": "DINAMICO_QUERY_SQL",
  "category": "<category or omit>",
  "owner": null,
  "template": "reports/<key>/template.jrxml",
  "parameterForm": "reports/<key>/params.xml",
  "query": "<query-key>",
  "orientation": "RETRATO",
  "allowedGroups": [],
  "allowedUsers": []
}
```

### Library
```json
{
  "key": "<key>",
  "name": "<name>",
  "type": "LOCAL",
  "authMode": "PUBLIC",
  "authToken": null,
  "mobileEnabled": false,
  "files": "libraries/<key>/"
}
```

### Process
```json
{
  "key": "<key>",
  "name": "<name>",
  "description": "<description or omit>",
  "bpmn": "processes/<key>/<key>.bpmn",
  "forms": {
    "desktop": "processes/<key>/<key>-desktop.xml",
    "mobile": null,
    "mobileAlternative": null
  }
}
```

## Step 5 — Report

Tell the user:
- Where the file was placed
- Registered in `vitruvio.json` under section `<type>` with key `<key>`
- Which fields were left at defaults and may need updating (e.g. `category`, `allowedGroups`, `description`)
- Reminder: keys are stable identifiers — changing them later is a breaking change