feat(metabase): expansion de funciones Python — documents, collections, permissions, validation

Añade un conjunto amplio de funciones al paquete python/functions/metabase:
- Nuevos modulos: collections.py, documents.py, maintenance.py, permissions.py, validation.py (+ test).
- Ampliacion de cards.py, dashboards.py, client.py e __init__.py para exponer las nuevas operaciones.
- Funciones de documentos (create/get/update/delete/archive/copy/move + comentarios), grupos y memberships, permission/collection graphs, copy/move de cards y dashboards, validacion de MBQL/SQL y payloads, actualizacion segura de dashboards y fix_null_ratio.
- .md por funcion con frontmatter para que fn index los registre.
- Actualiza pyproject.toml y uv.lock con las dependencias resultantes.

Impacto: ampliamente mas cobertura de la API de Metabase desde el registry, reutilizable por apps y analisis. No toca Go ni frontend.

python/functions/metabase/metabase_update_dashboard_safe.md

@@ -0,0 +1,95 @@
+---
+name: metabase_update_dashboard_safe
+kind: function
+lang: py
+domain: infra
+version: "1.0.0"
+purity: impure
+signature: "def metabase_update_dashboard_safe(client: MetabaseClient, dashboard_id: int, *, dashcards_update: list[dict] | None = None, dashcards_add: list[dict] | None = None, dashcards_remove: list[int] | None = None, extra_fields: dict | None = None) -> dict"
+description: "Wrapper sobre PUT /api/dashboard/:id que maneja los tres gotchas documentados: strip del campo '.card' denormalizado (evita 413), inclusion obligatoria de 'tabs' (evita 500 FK violation) y asignacion de IDs negativos a dashcards nuevos. Soporta reemplazo completo (dashcards_update), operaciones incrementales (add/remove) y actualizacion de campos extra del dashboard."
+tags: [metabase, dashboard, dashcard, api, wrapper, safe, put]
+uses_functions:
+  - metabase_get_dashboard_py_infra
+uses_types: []
+params:
+  - name: client
+    desc: "MetabaseClient autenticado con sesion activa."
+  - name: dashboard_id
+    desc: "ID entero del dashboard a actualizar."
+  - name: dashcards_update
+    desc: "Lista completa de dashcards que reemplaza el estado actual (full replace). Si se da, dashcards_add y dashcards_remove se ignoran. Cada dict puede incluir o no el campo 'card' — se strippea automaticamente."
+  - name: dashcards_add
+    desc: "Dashcards a añadir sobre los existentes. No deben incluir 'id' — la funcion asigna IDs negativos (-1, -2, ...). Se ignora si dashcards_update esta presente."
+  - name: dashcards_remove
+    desc: "Lista de IDs de dashcards existentes a eliminar del dashboard. Se aplica sobre existentes antes de añadir dashcards_add."
+  - name: extra_fields
+    desc: "Campos adicionales del dashboard a actualizar junto con las cards: name, description, parameters, archived, collection_id, etc."
+output: "Dict con resumen: {'added': [negative_ids_assigned], 'updated': count_existentes_conservados, 'removed': count_eliminados, 'response': dict_respuesta_PUT}"
+returns: []
+returns_optional: false
+error_type: "error_go_core"
+imports:
+  - httpx
+tested: false
+tests: []
+test_file_path: ""
+file_path: "python/functions/metabase/metabase_update_dashboard_safe.py"
+---
+
+## Gotchas que maneja
+
+### 1. 413 Payload Too Large — campo `.card` denormalizado
+GET /api/dashboard/:id devuelve cada dashcard con un campo `card` que contiene el objeto completo de la question (dataset_query, visualization_settings, result_metadata, etc.). Ese campo puede pesar varios KB por dashcard. PUT /api/dashboard/:id lo rechaza con 413 si se incluye.
+
+Esta funcion hace strip automatico, conservando solo los campos aceptados por la API:
+`id`, `card_id`, `dashboard_tab_id`, `col`, `row`, `size_x`, `size_y`, `parameter_mappings`, `visualization_settings`, `series`, `action_id`, `inline_parameters`.
+
+### 2. 500 FK violation — tabs ausentes
+Si el body del PUT no incluye `tabs`, Metabase interpreta que se deben borrar todas las tabs. Los dashcards que referencian esas tabs via `dashboard_tab_id` quedan con FK dangling y se produce 500 Internal Server Error.
+
+Esta funcion siempre hace GET del estado actual y re-incluye `current_tabs` en el body.
+
+### 3. IDs negativos para dashcards nuevos
+Los dashcards nuevos deben tener `id` negativo temporal (-1, -2, ...) en el payload del PUT. Sin el campo `id`, Metabase los ignora. Esta funcion asigna IDs negativos automaticamente a cualquier dashcard sin `id` en `dashcards_add` o en `dashcards_update`.
+
+## Ejemplo
+
+```python
+from metabase import MetabaseClient, metabase_update_dashboard_safe
+
+client = MetabaseClient('https://metabase.example.com', 'token...')
+
+# Añadir una card al dashboard
+result = metabase_update_dashboard_safe(
+    client,
+    dashboard_id=42,
+    dashcards_add=[{
+        "card_id": 100,
+        "col": 0,
+        "row": 0,
+        "size_x": 6,
+        "size_y": 4,
+        "parameter_mappings": [],
+        "visualization_settings": {},
+    }],
+)
+print(result["added"])   # [-1]
+print(result["updated"]) # N dashcards existentes conservados
+
+# Reemplazar todos los dashcards y cambiar nombre
+dash = client.request("GET", "/api/dashboard/42")
+cards = dash["dashcards"]
+cards.append({"card_id": 200, "col": 6, "row": 0, "size_x": 6, "size_y": 4})
+result = metabase_update_dashboard_safe(
+    client,
+    dashboard_id=42,
+    dashcards_update=cards,
+    extra_fields={"name": "Dashboard actualizado"},
+)
+```
+
+## Notas
+
+Realiza siempre 2 requests (GET + PUT). Para operaciones de solo metadata sin tocar cards (ej. cambiar nombre), usar `metabase_update_dashboard` directamente que solo hace PUT.
+
+En caso de 413 o 500, el mensaje de error incluye diagnostico del gotcha mas probable para facilitar debugging.