@roilab/crm-cli 0.18.0 → 0.21.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (43) hide show
  1. package/CHANGELOG.md +114 -0
  2. package/LICENSE +21 -21
  3. package/README.md +156 -119
  4. package/SKILL.md +116 -4
  5. package/SURFACE.txt +84 -24
  6. package/dist/bin/crm.js +11 -6
  7. package/dist/bin/crm.js.map +1 -1
  8. package/dist/src/commands/change.js +314 -0
  9. package/dist/src/commands/change.js.map +1 -0
  10. package/dist/src/commands/doc.js +21 -7
  11. package/dist/src/commands/doc.js.map +1 -1
  12. package/dist/src/commands/generic.js +76 -39
  13. package/dist/src/commands/generic.js.map +1 -1
  14. package/dist/src/commands/options.js +8 -1
  15. package/dist/src/commands/options.js.map +1 -1
  16. package/dist/src/commands/review.js +1 -1
  17. package/dist/src/commands/review.js.map +1 -1
  18. package/dist/src/commands/site.js +268 -0
  19. package/dist/src/commands/site.js.map +1 -0
  20. package/dist/src/commands/task-verify.js +197 -0
  21. package/dist/src/commands/task-verify.js.map +1 -0
  22. package/dist/src/commands/task.js +15 -28
  23. package/dist/src/commands/task.js.map +1 -1
  24. package/dist/src/transport/usage.js +137 -0
  25. package/dist/src/transport/usage.js.map +1 -0
  26. package/dist/src/types.js +7 -1
  27. package/dist/src/types.js.map +1 -1
  28. package/package.json +58 -58
  29. package/skill-bundles/tools/ahrefs-tool/SKILL.md +5 -5
  30. package/skill-bundles/tools/brightlocal-tool/SKILL.md +5 -5
  31. package/skill-bundles/tools/dataforseo-tool/SKILL.md +5 -5
  32. package/skill-bundles/tools/google-analytics-tool/SKILL.md +5 -5
  33. package/skill-bundles/tools/google-search-console-tool/SKILL.md +5 -5
  34. package/skill-bundles/tools/local-falcon-tool/SKILL.md +5 -5
  35. package/skill-bundles/tools/localseodata-tool/SKILL.md +5 -5
  36. package/skill-bundles/tools/lsa-spy-tool/SKILL.md +5 -5
  37. package/skill-bundles/tools/screaming-frog-tool/SKILL.md +5 -5
  38. package/skill-bundles/tools/semrush-tool/SKILL.md +5 -5
  39. package/skill-bundles/tools/serpapi-tool/SKILL.md +5 -5
  40. package/skill-bundles/tools/task-preflight/SKILL.md +157 -157
  41. package/skill-bundles/tools/whitespark-tool/SKILL.md +5 -5
  42. package/dist/src/commands/marketplace.js +0 -158
  43. package/dist/src/commands/marketplace.js.map +0 -1
package/CHANGELOG.md CHANGED
@@ -4,6 +4,120 @@ Todos los cambios notables se documentan aquí. El formato sigue
4
4
  [Keep a Changelog](https://keepachangelog.com/es/) y el versionado es
5
5
  [SemVer](https://semver.org/lang/es/).
6
6
 
7
+ ## [Sin publicar]
8
+
9
+ ## [0.21.0] — 2026-11-09
10
+
11
+ ### Added
12
+
13
+ - **`crm site rules` — reglas de publicación de una web.** Devuelve el perfil
14
+ del dominio, las normas propias de la web, las comprobaciones y el texto
15
+ completo de las skills y documentos de conocimiento que aplican, con su
16
+ versión. `crm site update` no escribe si no se ha leído la versión vigente en
17
+ las últimas 24 horas, bloquea lo que las incumple de forma medible (longitud
18
+ máxima de title y meta, términos prohibidos que introduce el cambio) y avisa
19
+ del resto. `crm site get` dice si ya se han leído (`rules.readByYou`).
20
+ - **`crm site update --author <id>`** (WordPress): cambia el autor de la
21
+ entrada; si no es el habitual de la web, avisa.
22
+
23
+ ## [0.20.0] — 2026-11-09
24
+
25
+ ### Added
26
+
27
+ - **`crm site` — cambiar la tienda y el blog desde el CRM.** `list`, `test`,
28
+ `get` y `update` sobre las webs conectadas en la ficha del dominio
29
+ (PrestaShop por webservice, WordPress por contraseña de aplicación). La
30
+ credencial no sale del servidor. `update` exige `--task` del mismo dominio,
31
+ escribe solo lo que cambia, vuelve a leer para confirmar lo guardado,
32
+ comprueba la página publicada y crea el registro de cambios con el antes y el
33
+ después reales. `--dry-run` enseña el diff. Scopes nuevos `sites:read` y
34
+ `sites:write` (staff).
35
+ - **`crm task tracking get|set` — seguimiento de URLs de una tarea.** Cada
36
+ registro de cambios (web, CLI o conector) mete su URL; el ámbito de la
37
+ revisión de métricas puede ser la lista de URLs, un patrón de página
38
+ (`--pattern '\.html$'`) o el dominio entero (`--domain`). Al completar la
39
+ tarea la revisión se programa sola a 28 días del cierre (`--verify-days`,
40
+ `--no-auto-verify`).
41
+ - **`--completed-at <date>` en `crm task update` y `crm task create`.** Fija la
42
+ fecha de completado (`YYYY-MM-DD` o ISO) para fechar trabajo cerrado fuera del
43
+ CRM. Solo staff, la tarea tiene que quedar en done (en la misma llamada vale
44
+ `--status done` o `--column` de done) y no admite fechas futuras. Una fecha
45
+ sin hora se guarda a las 12:00 UTC para que caiga en el mismo día en España.
46
+ Queda en el historial de la tarea.
47
+
48
+ ### Fixed
49
+
50
+ - **Revisiones de métricas con regex o listas de URLs medían cero.** Cuando la
51
+ medición iba directa a la API de Search Console, el operador se traducía dos
52
+ veces y `regex`, `not_regex`, `not_equals` y `not_contains` acababan como
53
+ `contains` literal; una lista de URLs se buscaba como un único texto. Ahora
54
+ los operadores se respetan y las listas se piden en tandas de regex.
55
+ - **La ayuda de `crm change log` decía que `--date` alimentaba la medición
56
+ antes/después.** Solo coloca el marcador en las gráficas; la revisión de
57
+ métricas cuenta desde que se completa la tarea.
58
+ - **`crm review approve task <id>` sobre una tarea con la marca REVISAR daba
59
+ `INTERNAL`.** Solo entendía propuestas en espera (`approvalStatus: pending`);
60
+ una tarea de agente ya aplicada con `reviewRequired` fallaba con "Task is not
61
+ pending". Ahora la acepta igual que el botón Aceptar de la web (mismo
62
+ historial y mismos avisos). Si no hay nada que aprobar devuelve `CONFLICT`
63
+ con el motivo, y los errores de ámbito o rol salen con su código
64
+ (`FORBIDDEN_SCOPE`, `FORBIDDEN_ROLE`, `NOT_FOUND`) en vez de `INTERNAL`.
65
+ - **Crear una tarea con `--status done` dejaba la fecha de completado vacía.**
66
+ Ahora se estampa al crearla, como hace la web.
67
+
68
+ ### Removed
69
+
70
+ - **`crm marketplace` (compare, domain, providers, import, scrape), `crm offer
71
+ list-tasks` y `crm task link-offer`.** El comparador de precios de enlaces y
72
+ las ofertas se fueron del CRM a pwn-control (`https://pwn.roilab.es/mercado`).
73
+ Los endpoints REST/MCP equivalentes (`/marketplace/*`, `/offers/*`) también
74
+ desaparecen, junto con los scopes `marketplace:read` y `marketplace:write`.
75
+ - `crm task complete-with-evidence --asset` solo acepta `backlink:<id>`.
76
+
77
+ ## [0.19.0] — 2026-08-04
78
+
79
+ ### Fixed
80
+
81
+ - **`crm change list` ya no exige `--domain`.** Era una restricción del CLI, no
82
+ del backend: la consulta sin dominio siempre estuvo soportada (rama
83
+ `by_workspace` + filtro de URL exacta). Al ser `requiredOption`, un
84
+ `crm change list --url <url>` fallaba por stderr y con `--quiet 2>/dev/null`
85
+ dejaba stdout vacío — indistinguible de "cero cambios". Ahora todos los
86
+ filtros son opcionales y combinables.
87
+ - **`--since` se perdía en silencio** en `crm change list`, `crm recall` y
88
+ `crm backlink lost`. Cuando la raíz declara el mismo flag que el subcomando,
89
+ commander guarda el valor en la raíz aunque lo escribas después del verbo, así
90
+ que `opts.since` llegaba `undefined` y el filtro nunca viajaba: devolvía más
91
+ filas de las pedidas, sin ningún error. Ahora los tres leen de `readFlags`,
92
+ que sí recorre la cadena. La trampa queda documentada en `options.ts`.
93
+ - **Un id de otra tabla ya no devuelve "Server Error".** `--domain` / `--task`
94
+ con un id que no es de esa tabla (o el host en vez del id) rebotaban contra el
95
+ validador `v.id()` de Convex, y producción censura ese error a un 500 genérico.
96
+ Ahora se normalizan con `ctx.db.normalizeId` y el fallo sale como
97
+ `INVALID_INPUT` con el nombre del flag y qué se esperaba.
98
+ - **Los errores de argumentos respetan el contrato de envoltura JSON.** Un
99
+ fallo de parseo de commander (opción obligatoria ausente, opción desconocida,
100
+ comando mal escrito) salía como texto plano por stderr con stdout vacío,
101
+ saltándose la promesa de "envoltura JSON siempre". Ahora sale como
102
+ `{ ok: false, error: { code: "USAGE", … } }` **por stdout** con exit code
103
+ `64`, mensaje en español y `details.raw` con el texto original de commander.
104
+ `--help` y `--version` siguen saliendo con código 0 y su salida de siempre.
105
+
106
+ ### Added
107
+
108
+ - **`crm change list --task <id>`.** Convex ya tenía `changeEvents.list({taskId})`
109
+ con índice `by_task` — es lo que pinta el cajón de la tarea — pero el CLI no
110
+ lo exponía. Es el filtro más barato de los cuatro.
111
+ - Endpoint nuevo `GET /api/v1/changes`: mismas filas que
112
+ `GET /api/v1/domains/:id/changes` pero con todos los filtros opcionales
113
+ (`domainId`, `taskId`, `url`, `sinceIso`). El endpoint por dominio se queda
114
+ para no romper a nadie y también acepta `taskId`.
115
+
116
+ ### Notes
117
+
118
+ - Despliega el servidor **antes** de publicar este CLI: `crm change list` pasa a
119
+ llamar a `/changes`, que no existe en despliegues anteriores.
120
+
7
121
  ## [0.18.0] — 2026-07-29
8
122
 
9
123
  ### Added
package/LICENSE CHANGED
@@ -1,21 +1,21 @@
1
- MIT License
2
-
3
- Copyright (c) 2026 ROILab Intelligence
4
-
5
- Permission is hereby granted, free of charge, to any person obtaining a copy
6
- of this software and associated documentation files (the "Software"), to deal
7
- in the Software without restriction, including without limitation the rights
8
- to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
- copies of the Software, and to permit persons to whom the Software is
10
- furnished to do so, subject to the following conditions:
11
-
12
- The above copyright notice and this permission notice shall be included in all
13
- copies or substantial portions of the Software.
14
-
15
- THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
- IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
- FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
- AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
- LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
- OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
- SOFTWARE.
1
+ MIT License
2
+
3
+ Copyright (c) 2026 ROILab Intelligence
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,119 +1,156 @@
1
- # @roilab/crm-cli
2
-
3
- > CLI for humans and AI agents to drive the ROILab SEO+CRM platform.
4
-
5
- CLI para el SEO + CRM de ROILab, pensado tanto para humanos como para agentes de
6
- IA (Claude Code, Cursor, Windsurf). Envoltura JSON siempre, exit codes numéricos,
7
- escrituras idempotentes y login sin pegar API keys en texto plano (flujo de
8
- dispositivo tipo OAuth).
9
-
10
- ## Instalación
11
-
12
- ### Agentes (recomendado)
13
-
14
- Sin instalación previa, siempre la última versión:
15
-
16
- ```bash
17
- npx -y @roilab/crm-cli@latest <comando>
18
- ```
19
-
20
- ### Humanos
21
-
22
- Para dejar `crm` en el PATH:
23
-
24
- ```bash
25
- npm i -g @roilab/crm-cli
26
- crm --help
27
- ```
28
-
29
- Actualiza con:
30
-
31
- ```bash
32
- npm i -g @roilab/crm-cli@latest
33
- ```
34
-
35
- El propio CLI comprueba una vez al día si hay una versión nueva en npm y avisa
36
- por stderr. Para forzar la comprobación, ejecuta `crm doctor`.
37
-
38
- ## Primer login (30 segundos)
39
-
40
- ```bash
41
- crm auth login --device-name mi-portatil
42
- # Abre la URL que aparece en el navegador, aprueba.
43
- crm auth whoami
44
- crm doctor
45
- ```
46
-
47
- El CLI guarda tokens rotativos en `~/.config/crm/credentials.json` (modo `0600`).
48
- Nunca se escribe una API key en claro en disco por esta vía.
49
-
50
- ## Comandos
51
-
52
- ```bash
53
- crm recall https://example.com/pricing
54
- crm task list --status todo --domain dom_xyz --limit 20
55
- crm task create --title "Arreglar H1 en /pricing" --domain dom_xyz --shadow
56
- crm comment create --task tsk_abc --body "Desplegado en prod" --kind agent_log
57
- crm domain metrics dom_xyz --start 2026-03-01 --end 2026-04-01 --markdown
58
- crm review list --mine
59
- ```
60
-
61
- `crm --help` imprime todos los sustantivos; `crm <noun> --help` imprime los
62
- verbos; la documentación completa vive en la app, pestaña **Documentación**, que
63
- se auto-genera desde el registro de endpoints — siempre refleja la versión
64
- servida.
65
-
66
- ## Adjuntar archivos (`--file`)
67
-
68
- `task create` / `task update` / `comment create` / `chat send` / `chat reply`
69
- aceptan `--file <ruta>` (repetible). Es **un flag, no un subcomando** — no
70
- existe `crm task attach` ni `crm upload`. El CLI sube cada archivo a Convex
71
- storage en dos pasos y manda los `attachments[]` en la misma escritura.
72
-
73
- ```bash
74
- crm task create --title "Migración H1" --domain dom_xyz \
75
- --file ./brief.pdf --file ./screenshot.png
76
-
77
- crm comment create --task tsk_abc --kind decision \
78
- --body "Cerrado, ver diff" --file ./after.png
79
-
80
- crm chat send "$TID" --body "captura del 404" --file ./bug.png
81
- ```
82
-
83
- Reglas:
84
-
85
- - Máx **10 MB por archivo** (rechazo local antes de tocar la red).
86
- - Aviso en stderr desde **2 MB** (`[AVISO] ... la subida puede tardar.`).
87
- - En `task update` la lista de adjuntos es **REEMPLAZO**, no merge. Usa
88
- `--clear-files` para vaciar; pasa los antiguos junto con los nuevos si
89
- quieres conservarlos.
90
- - `--body` se vuelve opcional cuando hay `--file`.
91
-
92
- ## Flags globales
93
-
94
- Disponibles en cada comando:
95
-
96
- - `--json` — envoltura JSON completa (por defecto).
97
- - `--quiet` — solo `data`.
98
- - `--ids-only` — un id por línea.
99
- - `--count` — un único entero.
100
- - `--markdown` — resumen legible (no es JSON).
101
- - `--jq <expr>` — jq mini (`.a`, `.a.b`, `.a[]`, `.a[].b`).
102
- - `--shadow` — fuerza que la escritura aterrice como propuesta pendiente de
103
- revisión humana.
104
- - `--wait-for-approval --timeout 30m` — bloquea hasta que un humano decida.
105
- - `--idempotency-key <key>` — idempotency key estable (automática en escrituras).
106
-
107
- ## Seguridad
108
-
109
- - Sin scripts `preinstall` / `postinstall` / `install` — nada que se ejecute al
110
- instalar el paquete.
111
- - Auth por flujo de dispositivo: no se comparten secretos entre máquinas; el
112
- access token caduca en 1 h y el refresh token rota en cada uso.
113
- - Archivo de credenciales con permisos `0600`, aislado por perfil.
114
- - Publicación con atestación de procedencia (`npm publish --provenance`) para
115
- que se pueda verificar el origen del tarball.
116
-
117
- ## Licencia
118
-
119
- MIT — ver [LICENSE](./LICENSE).
1
+ # @roilab/crm-cli
2
+
3
+ > CLI for humans and AI agents to drive the ROILab SEO+CRM platform.
4
+
5
+ CLI para el SEO + CRM de ROILab, pensado tanto para humanos como para agentes de
6
+ IA (Claude Code, Cursor, Windsurf). Envoltura JSON siempre, exit codes numéricos,
7
+ escrituras idempotentes y login sin pegar API keys en texto plano (flujo de
8
+ dispositivo tipo OAuth).
9
+
10
+ ## Instalación
11
+
12
+ ### Agentes (recomendado)
13
+
14
+ Sin instalación previa, siempre la última versión:
15
+
16
+ ```bash
17
+ npx -y @roilab/crm-cli@latest <comando>
18
+ ```
19
+
20
+ ### Humanos
21
+
22
+ Para dejar `crm` en el PATH:
23
+
24
+ ```bash
25
+ npm i -g @roilab/crm-cli
26
+ crm --help
27
+ ```
28
+
29
+ Actualiza con:
30
+
31
+ ```bash
32
+ npm i -g @roilab/crm-cli@latest
33
+ ```
34
+
35
+ El propio CLI comprueba una vez al día si hay una versión nueva en npm y avisa
36
+ por stderr. Para forzar la comprobación, ejecuta `crm doctor`.
37
+
38
+ ## Primer login (30 segundos)
39
+
40
+ ```bash
41
+ crm auth login --device-name mi-portatil
42
+ # Abre la URL que aparece en el navegador, aprueba.
43
+ crm auth whoami
44
+ crm doctor
45
+ ```
46
+
47
+ El CLI guarda tokens rotativos en `~/.config/crm/credentials.json` (modo `0600`).
48
+ Nunca se escribe una API key en claro en disco por esta vía.
49
+
50
+ ## Comandos
51
+
52
+ ```bash
53
+ crm recall https://example.com/pricing
54
+ crm task list --status todo --domain dom_xyz --limit 20
55
+ crm task create --title "Arreglar H1 en /pricing" --domain dom_xyz --shadow
56
+ crm task update tsk_abc --status done --completed-at 2026-10-28
57
+ crm review approve task tsk_abc # aprueba una propuesta o quita la marca REVISAR
58
+ crm comment create --task tsk_abc --body "Desplegado en prod" --kind agent_log
59
+ crm domain metrics dom_xyz --start 2026-03-01 --end 2026-04-01 --markdown
60
+ crm review list --mine
61
+ ```
62
+
63
+ `crm --help` imprime todos los sustantivos; `crm <noun> --help` imprime los
64
+ verbos; la documentación completa vive en la app, pestaña **Documentación**, que
65
+ se auto-genera desde el registro de endpoints — siempre refleja la versión
66
+ servida.
67
+
68
+ ## Cambiar la tienda y el blog (`crm site`)
69
+
70
+ Con las credenciales guardadas en el CRM (ficha del dominio → Conexiones con la
71
+ web) se leen y cambian el H1, el meta title, la meta description y el contenido
72
+ de la tienda PrestaShop y del blog WordPress. La credencial no sale del
73
+ servidor y cada cambio queda en el registro de cambios de su tarea.
74
+
75
+ ```bash
76
+ crm site list # webs que puedes usar
77
+ crm site rules --url https://www.tienda.com/ # reglas de publicación (obligatorio antes de escribir)
78
+ crm site get --url https://www.tienda.com/598-cbd # valores actuales
79
+ crm site update --task tsk_abc --url https://www.tienda.com/598-cbd \
80
+ --meta-title-file title.txt --meta-desc-file desc.txt --dry-run
81
+ crm site update --task tsk_abc --url https://www.tienda.com/598-cbd \
82
+ --meta-title-file title.txt --meta-desc-file desc.txt --note "por qué"
83
+ ```
84
+
85
+ `update` escribe solo lo que cambia, vuelve a leer la página para confirmar lo
86
+ guardado, comprueba la página publicada y registra el cambio con el antes y el
87
+ después reales. No escribe si no has leído en las últimas 24 horas la versión
88
+ vigente de las reglas de la web (perfil del dominio, normas, skills y documentos),
89
+ y bloquea lo que las incumple de forma medible.
90
+
91
+ ## Seguimiento de URLs (`crm task tracking`)
92
+
93
+ Cada cambio registrado mete su URL en el seguimiento de la tarea; al
94
+ completarla, la revisión de métricas se programa sola (28 días por defecto) y
95
+ mide esas URLs en Search Console. Para medir un grupo o el dominio entero:
96
+
97
+ ```bash
98
+ crm task tracking get tsk_abc
99
+ crm task tracking set tsk_abc --pattern '\.html$' # todas las fichas
100
+ crm task tracking set tsk_abc --domain
101
+ ```
102
+
103
+ ## Adjuntar archivos (`--file`)
104
+
105
+ `task create` / `task update` / `comment create` / `chat send` / `chat reply`
106
+ aceptan `--file <ruta>` (repetible). Es **un flag, no un subcomando** — no
107
+ existe `crm task attach` ni `crm upload`. El CLI sube cada archivo a Convex
108
+ storage en dos pasos y manda los `attachments[]` en la misma escritura.
109
+
110
+ ```bash
111
+ crm task create --title "Migración H1" --domain dom_xyz \
112
+ --file ./brief.pdf --file ./screenshot.png
113
+
114
+ crm comment create --task tsk_abc --kind decision \
115
+ --body "Cerrado, ver diff" --file ./after.png
116
+
117
+ crm chat send "$TID" --body "captura del 404" --file ./bug.png
118
+ ```
119
+
120
+ Reglas:
121
+
122
+ - Máx **10 MB por archivo** (rechazo local antes de tocar la red).
123
+ - Aviso en stderr desde **2 MB** (`[AVISO] ... la subida puede tardar.`).
124
+ - En `task update` la lista de adjuntos es **REEMPLAZO**, no merge. Usa
125
+ `--clear-files` para vaciar; pasa los antiguos junto con los nuevos si
126
+ quieres conservarlos.
127
+ - `--body` se vuelve opcional cuando hay `--file`.
128
+
129
+ ## Flags globales
130
+
131
+ Disponibles en cada comando:
132
+
133
+ - `--json` — envoltura JSON completa (por defecto).
134
+ - `--quiet` — solo `data`.
135
+ - `--ids-only` — un id por línea.
136
+ - `--count` — un único entero.
137
+ - `--markdown` — resumen legible (no es JSON).
138
+ - `--jq <expr>` — jq mini (`.a`, `.a.b`, `.a[]`, `.a[].b`).
139
+ - `--shadow` — fuerza que la escritura aterrice como propuesta pendiente de
140
+ revisión humana.
141
+ - `--wait-for-approval --timeout 30m` — bloquea hasta que un humano decida.
142
+ - `--idempotency-key <key>` — idempotency key estable (automática en escrituras).
143
+
144
+ ## Seguridad
145
+
146
+ - Sin scripts `preinstall` / `postinstall` / `install` — nada que se ejecute al
147
+ instalar el paquete.
148
+ - Auth por flujo de dispositivo: no se comparten secretos entre máquinas; el
149
+ access token caduca en 1 h y el refresh token rota en cada uso.
150
+ - Archivo de credenciales con permisos `0600`, aislado por perfil.
151
+ - Publicación con atestación de procedencia (`npm publish --provenance`) para
152
+ que se pueda verificar el origen del tarball.
153
+
154
+ ## Licencia
155
+
156
+ MIT — ver [LICENSE](./LICENSE).
package/SKILL.md CHANGED
@@ -123,9 +123,20 @@ Errors **always** appear on stderr with full envelope, bypassing `--jq`. Exit co
123
123
  --body "Cerrado: H1 reemplazado, A/B +12% CTR a 14d (ver crm change list)"
124
124
  ```
125
125
 
126
+ **SEO work whose effect shows up weeks later** (metas, contenido, enlazado interno, enlaces): complete it AND schedule the metric review in one step, instead of a bare `--status done`. On that day staff are notified and the task enters the review queue with a before/after snapshot (see § Revisión de métricas):
127
+ ```bash
128
+ crm task verify schedule tsk_abc --complete --in 30 --criteria "CTR de /categoria/x por encima del 3 % (hoy 1,9 %)"
129
+ ```
130
+ Defaults: 30 días; 60 para contenido. Write `--criteria` as a measurable target with its current baseline — it is what the reviewer (human or agent) checks first.
131
+
132
+ **Work closed outside the CRM** (done last week, logged today): date it with `--completed-at` instead of leaving today's stamp. Staff keys only; the task must end the call in done, and future dates are rejected:
133
+ ```bash
134
+ crm task update tsk_abc --status done --completed-at 2026-10-23
135
+ ```
136
+
126
137
  4. **Use `reviewRequired`**. Your task creates default to `reviewRequired=true` — the human sees them in a dedicated inbox section. Only pass `--no-review` for low-stakes rework (e.g. re-filing a recurring instance). (The flag has only been wired end-to-end since 0.6.0 — earlier CLIs sent it but the server stripped it.)
127
138
 
128
- **Read side — when you see `reviewRequired: true` on a task you didn't create**: treat it as tentative. The row is live but a human hasn't acknowledged it yet, and may still edit, reassign, or reject the framing. Don't build downstream work that assumes it's settled (no offers linked to it, no auto-complete on its goals, no marking siblings as duplicates of it). You can't approve your own writes — only humans clear the flag. If you're blocked waiting, leave a `--kind decision` agent_log comment, don't change status. Filter the queue with `crm task list --review-pending` (or `GET /tasks?reviewRequired=true`).
139
+ **Read side — when you see `reviewRequired: true` on a task you didn't create**: treat it as tentative. The row is live but a human hasn't acknowledged it yet, and may still edit, reassign, or reject the framing. Don't build downstream work that assumes it's settled (no offers linked to it, no auto-complete on its goals, no marking siblings as duplicates of it). Don't approve your own writes: only humans decide to clear the flag. `crm review approve task <id>` does clear it (same as the web Aceptar button), so run it only when a human explicitly asks you to approve that task. If you're blocked waiting, leave a `--kind decision` agent_log comment, don't change status. Filter the queue with `crm task list --review-pending` (or `GET /tasks?reviewRequired=true`).
129
140
 
130
141
  5. **Every write gets an idempotency key**. The CLI autogenerates one per invocation, so retries within a single command are safe. If you're orchestrating retries across invocations, pass `--idempotency-key <ulid>` so the retry replays instead of double-creating.
131
142
 
@@ -160,6 +171,107 @@ Errors **always** appear on stderr with full envelope, bypassing `--jq`. Exit co
160
171
 
161
172
  **Do NOT confuse this with `[[feedback_task_refs_use_chip_syntax]]`**: inside task descriptions, comments, and chat bodies you still use `#[Title](taskId)` chips, never raw dashboard URLs. The dashboard URL goes only in your chat reply to the human reviewing your work — that is where they need a one-click destination.
162
173
 
174
+ 8. **Cada cambio on-page que publiques, regístralo en su tarea.** Si lo aplicas con `crm site update` el registro se crea solo (con el antes y el después reales). Si lo publicas por otra vía (back office, editor de WordPress), usa `crm change log`. El registro pinta el marcador en las gráficas y mete la URL en el seguimiento de la tarea, que es lo que medirá su revisión de métricas (ver «Cambiar la tienda y el blog»).
175
+ - **Nunca registres un cambio sin verificarlo en vivo antes.** Abre la URL publicada (sin caché) y comprueba que el valor nuevo está ahí. Si no lo ves, no lo registres: arregla la publicación o avisa.
176
+ - **Una URL por registro.** Varios cambios en la misma URL → un solo `crm change log` con `--items-file`; varias URLs → un comando por URL.
177
+ - **`--date` = día real de publicación**, no el de hoy si lo publicaste antes.
178
+ - Metas y H1: `--before` (valor anterior) y `--after` (nuevo). Contenido largo: `--type content` con `--note "qué cambió"` y, si quieres, `--after-file`; no hace falta pegar el texto entero. Textos con acentos o saltos de línea, siempre por fichero (`--before-file` / `--after-file` / `--note-file`).
179
+ - Lotes (CSV de URLs): un comando por fila en un bucle, con `--idempotency-key` estable (p. ej. `<taskId>-<n.º de fila>`) para que reintentar el bucle no duplique filas.
180
+ - No hay `--shadow` ni revisión para los cambios: se guardan directos. Si tu key tiene "Change events" en shadow, el servidor responde `BUSINESS_RULE` y hay que cambiar la política.
181
+
182
+ ```bash
183
+ crm change log --task ms7abc --url https://tienda.com/zapatillas \
184
+ --type metaTitle --before "Zapatillas | Tienda" --after-file title.txt --date 2026-10-19
185
+ crm change log --task ms7abc --url https://tienda.com/guia-tallas \
186
+ --type content --note "Reescrita la sección de tallas y añadida tabla de equivalencias"
187
+ ```
188
+
189
+ ## Cambiar la tienda y el blog (`crm site`)
190
+
191
+ El CRM guarda cifradas las credenciales de la tienda (PrestaShop, webservice) y del blog (WordPress, contraseña de aplicación) de cada dominio. Tú nunca las ves: `crm site` habla con la web desde el servidor. Una conexión la usan owner/admin y los miembros autorizados en ella (que además tengan asignado el cliente).
192
+
193
+ **Reglas de publicación (obligatorio).** Cada web tiene sus reglas en el CRM: el perfil del dominio (posicionamiento, tono, audiencia, guía de contenidos), normas propias (por ejemplo, quién es el autor habitual del blog), comprobaciones y el texto completo de las skills y documentos de conocimiento que aplican. Léelas al empezar a trabajar con una web y aplícalas a todo lo que redactes:
194
+
195
+ ```bash
196
+ crm site rules --url <url-de-la-web> # paquete completo + versión; deja constancia de la lectura (24 h)
197
+ ```
198
+
199
+ `crm site get` te dice en `rules.readByYou` si ya tienes la versión vigente. `crm site update` **no escribe** si no la has leído en las últimas 24 horas o si las reglas han cambiado desde entonces: vuelve a leerlas. El servidor bloquea lo medible (title o meta por encima del máximo de la web, términos prohibidos que tu cambio introduce) y avisa del resto (longitud recomendada, enlaces nuevos a dominios no previstos, un autor distinto del habitual). Lo que no se puede medir (tono, estilo, datos de marca) depende de ti: es lo que traen las skills y los documentos.
200
+
201
+ **Flujo obligatorio para cada página:**
202
+
203
+ ```bash
204
+ crm site rules --url <url> # al empezar con cada web (y si cambia la versión)
205
+ crm task get <taskId> # qué pide la tarea
206
+ crm recall <url> # trabajo previo sobre la URL
207
+ crm site get --url <url> --quiet > actual.json # valores de AHORA (h1, metaTitle, metaDescription, content, summary)
208
+ # … preparas los textos nuevos en ficheros UTF-8 …
209
+ crm site update --task <taskId> --url <url> --meta-title-file t.txt --meta-desc-file d.txt --dry-run # diff
210
+ crm site update --task <taskId> --url <url> --meta-title-file t.txt --meta-desc-file d.txt --note "por qué"
211
+ ```
212
+
213
+ Reglas:
214
+ - **`--task` siempre**, y la tarea tiene que ser del mismo dominio que la web. Sin tarea no se escribe.
215
+ - **Lee antes de escribir** (`crm site get`) y parte de ese texto para el contenido: `--content-file` sustituye el HTML entero.
216
+ - **Lee la respuesta:** `applied` (lo que la relectura confirma), `notApplied` (lo que la web no guardó; ej. un plugin que corta el guardado), `liveCheck` (`ok`, `cached` = la caché aún sirve lo viejo, `mismatch`, `unverifiable` = la página no responde 200) y `warnings`. Si hay `notApplied` o `mismatch`, dilo en la tarea; no lo des por hecho.
217
+ - **El registro de cambios se crea solo** con lo aplicado. No repitas con `crm change log`.
218
+ - **Campos:** `h1` (título del post o página, nombre del producto o la categoría, título del CMS), `metaTitle`, `metaDescription`, `content` (HTML: cuerpo del post, descripción del producto o de la categoría, contenido del CMS), `summary` (extracto en WP, descripción corta del producto, descripción adicional de abajo en la categoría) y, solo en WordPress, `author` (`--author <id>`; las reglas dicen cuál es el habitual, cámbialo solo si la tarea lo pide). Los CMS de PrestaShop no tienen `summary`.
219
+ - **Fuera de alcance:** URL/slug (exige redirección), noindex/canonical, precios, stock, borrar. Eso va por tarea a quien corresponda.
220
+ - **PrestaShop multitienda:** escribe en la tienda y el idioma de la conexión y conserva los demás idiomas. PrestaShop guarda el objeto entero y su filtro de HTML puede reescribir textos de otros idiomas (igual que desde el back office): sale en `warnings`.
221
+ - **Sin ráfagas.** Una página detrás de otra; hay servidores que bloquean la IP ante muchas peticiones seguidas.
222
+ - **URL que no se reconoce** (rutas propias de un módulo): usa `--ref product:<id>` / `category:<id>` / `cms:<id>` / `post:<id>` / `page:<id>` junto a `--url`.
223
+
224
+ ### Seguimiento de URLs (`crm task tracking`)
225
+
226
+ Cada registro de cambios añade su URL al seguimiento de la tarea y la tarea queda vinculada a la propiedad GSC del dominio filtrada a esas URLs. Al completarla, la revisión de métricas se programa sola a 28 días del cierre (`--verify-days` para cambiarlo). Si el trabajo no es de URLs sueltas, cambia el ámbito:
227
+
228
+ ```bash
229
+ crm task tracking get <taskId>
230
+ crm task tracking set <taskId> --pattern '\.html$' # todas las fichas (regex RE2 de GSC)
231
+ crm task tracking set <taskId> --pattern /blog/ --operator contains
232
+ crm task tracking set <taskId> --urls-file urls.txt # lista exacta (una por línea)
233
+ crm task tracking set <taskId> --domain # dominio entero
234
+ crm task tracking set <taskId> --no-auto-verify # programarla a mano
235
+ ```
236
+
237
+ Las listas van como un solo filtro (GSC combina filtros con AND: diez `equals` darían cero). Las URLs se guardan con y sin barra final para que casen con cómo las tenga Search Console.
238
+
239
+ ## Revisión de métricas (rutina diaria)
240
+
241
+ Una tarea SEO se **aplica** (se completa, `completedAt` = día del cambio) y se **revisa** N días después. Ese día el servidor:
242
+ 1. la pasa a `due` y avisa a quien la programó y a sus responsables (solo equipo),
243
+ 2. calcula la foto con Search Console en vivo sobre el ámbito de la tarea (URLs del seguimiento, `crm task tracking get`; si no hay, la propiedad vinculada; si no, el dominio). En `verification.snapshot.analysis`:
244
+ - **Métricas:** clics (todos los dispositivos); impresiones, CTR, posición y número de keywords (solo móvil: el escritorio de GB va inflado).
245
+ - **Comparaciones por métrica:** `pop` (antes → después, ventanas simétricas al día aplicado), `yoy` (después contra las mismas fechas de hace 52 semanas), `popLY` (el antes → después de hace un año: estacionalidad de esas URLs), `vsLastYear` (este año ajustado por el pasado), `controlPop` y `net` (efecto por encima del grupo de control). Volumen y CTR en tanto por uno; posición en diferencia absoluta (negativa = mejora).
246
+ - **Grupo de control:** la misma sección sin las URLs de la tarea (fichas, categorías o blog) o el resto del dominio; con el dominio entero no hay control y se usa el año anterior.
247
+ - **`noiseBand`** (variación semanal normal frente al control, en escala logarítmica), **`suggestion`** (veredicto propuesto por los clics netos, con un mínimo del 5 % y por encima del ruido; `inconclusive` con poco volumen o ruido de más de ±50 %), **`reasons`** (explicación en español), **`googleUpdates`** e **`otherChanges`** (otras tareas que tocaron esas URLs en las ventanas);
248
+ y las metas de ranking de la tarea,
249
+ 3. la pone en la cola de la bandeja ("Revisiones de métricas").
250
+
251
+ Estados: `scheduled` → `due` → `proposed` (un agente dejó análisis) → `resolved` (una persona decidió). Veredictos: `positive` · `neutral` · `negative` · `inconclusive`.
252
+
253
+ **Rutina del agente** (una vez al día, o cuando te lo pidan):
254
+
255
+ ```bash
256
+ crm task verify list # vencidas + propuestas, con la foto
257
+ crm task verify show tsk_abc # criterio, foto, metas, propuesta previa
258
+ crm task get tsk_abc # qué se hizo (descripción, dominio, propiedades)
259
+ crm change list --task tsk_abc # cambios on-page registrados y sus fechas
260
+ crm change list --domain <id> --since <iso> # otros cambios del dominio en la ventana (confusores)
261
+ crm recall <url> # historia de la URL (tareas, comentarios, enlaces)
262
+ crm gsc query --property <id> --dimension query --filters "page==<url>" ... # si la foto no basta
263
+ crm task verify resolve tsk_abc --verdict positive --note-file analisis.md
264
+ ```
265
+
266
+ Reglas:
267
+ - **Tú solo propones.** Tu `resolve` deja la revisión en `proposed`; una persona la confirma (o cambia el veredicto) en la bandeja. No intentes cerrarla de otra forma ni reabrir la tarea tú: si el veredicto es `negative`, dilo en la nota y propón el siguiente paso; la persona decide si la reabre.
268
+ - **Solo cuando ya venció.** Antes de la fecha el servidor rechaza la propuesta: los datos aún no son comparables.
269
+ - **Parte de `analysis.suggestion` y `analysis.reasons`, pero compruébalos:** si `otherChanges` o `googleUpdates` explican el movimiento, o el control no es comparable, dilo y cambia el veredicto.
270
+ - **La nota es obligatoria y es el producto.** Qué métrica se movió, cuánto, contra qué ventana, si coincide con el criterio, y qué más pudo influir (estacionalidad, otros cambios del dominio en `crm change list`, actualizaciones de Google). Sin adornos: números y conclusión.
271
+ - **`inconclusive` es una respuesta válida** (pocos datos, ventana corta, ruido). Si crees que con más tiempo se verá, mejor `crm task verify snooze tsk_abc --in 14` que forzar un veredicto.
272
+ - **Foto vieja o sin datos** → `crm task verify measure tsk_abc` (máx. 1 vez/hora; Tinybird tiene cuota diaria) y vuelve a `show` en unos segundos.
273
+ - Todo esto es interno: nunca lo menciones en comentarios visibles para el cliente.
274
+
163
275
  ## Descubrir tableros (antes de colocar o mover tareas)
164
276
 
165
277
  `crm board list` enumera los tableros del workspace (`_id`, `name`, `clientId`,
@@ -426,9 +538,9 @@ crm task create \
426
538
 
427
539
  # Change events (log de cambios on-page): disponibles en cualquier tarea
428
540
  # anclada a un dominio (task.domainId) — el backend rechaza tareas sin
429
- # dominio. Lectura via GET /api/v1/domains/<domainId>/changes o
430
- # `crm change list`. No hay verbo de escritura todavía (ni CLI ni REST);
431
- # los registros se crean desde la UI web de la tarea.
541
+ # dominio. Lectura con `crm change list` (GET /changes); escritura con
542
+ # `crm change log` (POST /changes) — ver regla 8. Verifica en vivo antes.
543
+ crm change log --task ms7abc --type h1 --before "Zapatillas" --after "Zapatillas running hombre"
432
544
 
433
545
  # Search across everything
434
546
  crm search "meta title" --kind change --domain dom_xyz --limit 5