Actualiza toolkit operativo y documentación

coolify_skill/TOOLS.md

@@ -2,6 +2,33 @@
 
 All commands assume PowerShell from the project root.
 
+> **Canonical catalog:** [`docs/TOOL-INDEX.md`](../docs/TOOL-INDEX.md). This file
+> holds usage examples; the index holds verified signatures, env requirements,
+> read-only/mutating classification and the gotchas. Read its §1 first.
+
+## Two gotchas specific to this wrapper
+
+**1. `-Raw` is inverted.** `Invoke-CoolifyApi.ps1` returns a **JSON string** by
+default and **PowerShell objects with `-Raw`**. Filtering the default output
+silently yields nothing — no error:
+
+```powershell
+# WRONG: $r is a System.String, so this prints an empty row
+.\coolify_skill\scripts\Invoke-CoolifyApi.ps1 -Path "/resources" | Select-Object name, uuid
+
+# RIGHT
+.\coolify_skill\scripts\Invoke-CoolifyApi.ps1 -Path "/resources" -Raw | Select-Object name, uuid
+```
+
+**2. `/applications/*` 404s through the public hostname — that block is
+Cloudflare's, not Coolify's** (re-verified 2026-08-29 on v4.3.14: same token,
+same route → 200 against the origin `http://192.168.0.117:8000/api/v1`, 404 via
+`https://coolify.urieljareth.org`). For those endpoints use
+`$env:COOLIFY_API_URL_ORIGIN`. Also: state-changing endpoints are POST-only
+since v4.2 (`GET /deploy` → 405). Endpoints that work through either path:
+`/version`, `/resources`, `/services`, `/databases`, `/projects`, `/servers`,
+`/teams`, `/deployments`. Use `/resources` to enumerate apps.
+
 ## Environment
 
 Load private values from an ignored local file:
@@ -31,6 +58,29 @@ $env:COOLIFY_TOKEN = "REPLACE_WITH_TOKEN"
 .\scripts\Invoke-ProxmoxSsh.ps1 -Command "pct exec 102 -- docker volume ls"
 ```
 
+## A New Service Is Green In Coolify But Its Domain Returns 503
+
+Coolify's green dot means the container is `running`. Traefik only routes a
+container Docker reports `healthy`. A brand-new service is `running` long before
+it is `healthy`, so its route does not exist yet and the request falls through to
+Coolify's catch-all (`noop` service, empty server list) — which is what prints
+`no available server`.
+
+```powershell
+# Contrast running vs healthy, flag a too-short start_period, probe the domain.
+.\coolify_skill\scripts\Test-CoolifyServiceReady.ps1 -Uuid <resource-uuid>
+
+# First boot on this host can take minutes (HDD-backed loopback rootfs). Wait it out.
+.\coolify_skill\scripts\Test-CoolifyServiceReady.ps1 -Uuid <resource-uuid> -WaitSeconds 600
+```
+
+Read the status code before changing anything:
+
+- `502 Bad Gateway` — the route exists, the backend refuses. App or port problem.
+- `503 no available server` — there is no route. Usually still starting.
+  **Do not redeploy**: that restarts the entrypoint from scratch and restarts the
+  slow boot. See TOOL-INDEX.md 1.5.
+
 ## Logs And Inspect
 
 ```powershell
@@ -40,14 +90,37 @@ $env:COOLIFY_TOKEN = "REPLACE_WITH_TOKEN"
 
 ## Coolify API
 
+Verified working on this instance (2026-08-07):
+
 ```powershell
 .\coolify_skill\scripts\Invoke-CoolifyApi.ps1 -Path "/version"
-.\coolify_skill\scripts\Invoke-CoolifyApi.ps1 -Path "/projects"
-.\coolify_skill\scripts\Invoke-CoolifyApi.ps1 -Path "/servers"
-.\coolify_skill\scripts\Invoke-CoolifyApi.ps1 -Path "/applications"
-.\coolify_skill\scripts\Invoke-CoolifyApi.ps1 -Path "/services"
-.\coolify_skill\scripts\Invoke-CoolifyApi.ps1 -Path "/databases"
-.\coolify_skill\scripts\Invoke-CoolifyApi.ps1 -Path "/deployments"
+.\coolify_skill\scripts\Invoke-CoolifyApi.ps1 -Path "/resources"    # 28 — the app inventory
+.\coolify_skill\scripts\Invoke-CoolifyApi.ps1 -Path "/projects"     # 7
+.\coolify_skill\scripts\Invoke-CoolifyApi.ps1 -Path "/services"     # 14
+.\coolify_skill\scripts\Invoke-CoolifyApi.ps1 -Path "/databases"    # 5
+.\coolify_skill\scripts\Invoke-CoolifyApi.ps1 -Path "/servers"      # 1
+.\coolify_skill\scripts\Invoke-CoolifyApi.ps1 -Path "/teams"        # 1
+.\coolify_skill\scripts\Invoke-CoolifyApi.ps1 -Path "/deployments"  # in-flight deploys
+```
+
+**`/applications` and its whole namespace 404 through the public hostname
+(Cloudflare edge block) but work via the origin** — point
+`COOLIFY_API_URL` at `http://192.168.0.117:8000/api/v1` for those calls. Either
+way, to enumerate applications and resolve a name or uuid, `/resources` is the
+reliable inventory:
+
+```powershell
+.\coolify_skill\scripts\Invoke-CoolifyApi.ps1 -Path "/resources" -Raw |
+    Where-Object { $_.name -match 'chatwoot' } | Select-Object name, uuid, fqdn
+```
+
+### Resolving a container name from a resource
+
+Container names are `<service>-<uuid>` plus an optional build suffix, so they are
+not guessable and **change when a redeploy recreates the container**:
+
+```powershell
+.\scripts\Invoke-ProxmoxSsh.ps1 -Command "pct exec 102 -- docker ps --format '{{.Names}}' | grep -i <app>"
 ```
 
 For write calls, prepare the JSON body first and ask for confirmation: