@roilab/crm-cli 0.4.0 → 0.7.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.
package/CHANGELOG.md CHANGED
@@ -1,144 +1,225 @@
1
- # Changelog
2
-
3
- Todos los cambios notables se documentan aquí. El formato sigue
4
- [Keep a Changelog](https://keepachangelog.com/es/) y el versionado es
5
- [SemVer](https://semver.org/lang/es/).
6
-
7
- ## [Unreleased]
8
-
9
- _Ningún cambio pendiente todavía._
10
-
11
- ## [0.4.0] — 2026-05-12
12
-
13
- ### Added
14
-
15
- - **Task participants completos.** `task create` y `task update` aceptan
16
- `--collaborator <id...>` (followers — notificados pero no responsables) además
17
- de `--assignee`. También cierra otros huecos del registro REST que el CLI no
18
- exponía: `--start <date>`, `--completion-strategy <all|any|manual>`,
19
- `--board <id>` (mover de tablero en `update`), y `--tag <id...>` /
20
- `--assignee <id...>` en `update`. Equivalente Convex: el campo
21
- `tasks.collaborators` ya existía pero no estaba enrutado por el gateway ni
22
- el endpoint REST — ahora sí.
23
- - **`crm backlink {pending,verify,reject,rejection-report}`.** Cubre el flujo
24
- humano de QA de backlinks. `reject` requiere `--reason` estructurado del
25
- catálogo (`spammy_source | wrong_anchor | wrong_target | nofollow_unexpected
26
- | dead_on_arrival | duplicate | policy_violation | other`).
27
- - **`crm review feedback [--retryable-only]`.** Loop de iteración del agente
28
- documentado en `SKILL.md`: lee tus propuestas rechazadas con `rejectionReason`
29
- + `allowRetry` para re-proponer. Mapea a `GET /reviews/feedback`.
30
- - **`crm review bulk-approve` / `bulk-reject`.** Aprueba o rechaza hasta 100
31
- propuestas en una sola llamada. Items por stdin (NDJSON o tokens `kind:id`),
32
- típico encadenado: `crm review list --jq '.data[] | "\(.kind):\(.id)"' | crm
33
- review bulk-approve`.
34
- - **`crm report {create,update,delete}`.** Schedules CRUD. Body JSON por
35
- `--body <json | @path | ->` para no aplanar la unión scope/cadence/approval
36
- en flags mutuamente dependientes.
37
- - **`crm access {request,list,approve,deny}`.** Namespace canónico para
38
- solicitudes de acceso vía chat. Las variantes antiguas bajo `crm task
39
- {request-access,list-access-requests,approve-access,deny-access}` siguen
40
- funcionando con un aviso `[DEPRECATED]` en stderr; se retiran en la
41
- próxima release mayor.
42
- - **`crm commands`.** Dump JSON del árbol completo del CLI (verbos, args,
43
- flags) para que los agentes introspeccionen la superficie sin parsear
44
- `--help`. Devuelve `{ data: { tree, flat } }`.
45
- - **`crm dashboard summary --start --end`.** Time-series agregado de todo el
46
- workspace para overviews. Mapea a `GET /dashboard/summary`.
47
- - **`crm domain get <id>`.** Single-domain fetch con tags + propiedades
48
- resueltas. Nuevo endpoint `GET /domains/:id` en el registro REST.
49
- - **`crm time list-task <taskId>`.** Lista entradas de tiempo de una tarea
50
- sin filtro por fecha. Mapea a `GET /tasks/:taskId/time-entries`.
51
-
52
- ### Changed
53
-
54
- - **`task update --client-visible` ahora es simétrico.** Antes era
55
- `--client-visible <bool>` (string parseado). Ahora se usan los flags
56
- booleanos de commander: `--client-visible` para marcar visible,
57
- `--no-client-visible` para marcar interna. Omitir el flag deja la
58
- visibilidad sin cambios. `task create --client-visible` ya era el flag
59
- booleano correcto.
60
- - **Notificación de actualización a usuarios — dos canales nuevos:**
61
- - **Cache auto-refresh en segundo plano.** Al ejecutar cualquier comando
62
- el CLI lanza un hijo *detached* (no bloquea el foreground) que
63
- refresca `~/.config/crm/cache.json` contra `registry.npmjs.org` cuando
64
- está caducada (>24h) o no existe. Antes solo `crm doctor` refrescaba;
65
- ahora cualquier invocación cierra el hueco "nunca corro doctor". El
66
- nudge instantáneo (`maybeNudgeFromCache`) sigue siendo síncrono y sin
67
- red — el hijo solo escribe la cache para la siguiente invocación.
68
- - **`User-Agent` + `X-Crm-Cli-Version` en cada llamada HTTP.** El
69
- servidor compara contra `RECOMMENDED_CLI_VERSION` y `MIN_CLI_VERSION`
70
- en `src/lib/cli-version-policy.ts`. Si el caller va por detrás, estampa
71
- `meta.cliUpdate: { current, recommended, severity }` en cada envelope
72
- (tanto éxito como error, también en replays idempotentes). El CLI lee
73
- `meta.cliUpdate` y muestra un aviso por stderr una vez por proceso —
74
- "soft" para upgrades recomendados, "ATENCIÓN" para versiones por
75
- debajo del mínimo. Mecanismo controlado para forzar avisos sin esperar
76
- a la TTL de cache de 24h.
77
-
78
- ## [0.3.0] — 2026-05-04
79
-
80
- ### Added
81
- - `crm task preflight --title <t> [--url <u>] [--domain <id>]` — bundle de
82
- un round-trip que un agente debe ejecutar **antes** de cualquier
83
- `crm task create`. Devuelve seis secciones acotadas (≤5 items por
84
- defecto): `similarTasks` (FTS de título re-rankeado por Jaccard +
85
- recencia + bonus same-domain), `recall` (cuando pasas `--url` —
86
- fan-out por URL como en `crm recall`, capeado a 10), `recentChanges`,
87
- `urlScopedTasks` (tareas abiertas ya enlazadas a esa URL),
88
- `recentBacklinks`, `openTaskCounts` del dominio y `hints[]` en
89
- español. El `summary` del envelope prioriza la pista accionable
90
- (duplicado → cargas en URL → similares → adelante).
91
- Equivalente REST: `GET /tasks/preflight?title=…&url=…&domainId=…`.
92
- - Skill bundle nuevo `task-preflight` (lazy) con árbol de decisión:
93
- cuándo NO crear, cuándo cargar GSC/GA4 vivo después del preflight,
94
- anti-patrones, ejemplo realista. Cárgalo sólo si el envelope deja
95
- al agente en duda — el `summary` resuelve el 80% de los casos.
96
-
97
- ### Changed
98
- - `cli/SKILL.md` — la regla operativa #1 pasa de "always recall before
99
- creating" a el **ritual obligatorio del preflight**. Documenta que no
100
- hay que pre-crawlear con Screaming Frog para entender una URL puntual
101
- (usa `WebFetch` 1-shot) y que GSC/GA4 vivos se llaman *después* del
102
- preflight, no antes.
103
- - `tool-routing` añade fila para "decidir si crear tarea" → apunta a
104
- `task-preflight` antes de cargar cualquier otro skill.
105
-
106
- ## [0.2.0] — 2026-05-01
107
-
108
- ### Added
109
- - `crm task list --review-pending` y `--review-acked` para filtrar tareas
110
- según `reviewRequired`. Útil para que un agente encuentre rápidamente las
111
- tareas que él mismo creó y siguen pendientes de validación humana.
112
- Equivalente REST: `GET /tasks?reviewRequired=true|false`.
113
- - Banner `⚠ REVISAR` en el formato `--markdown`/`--styled`: cuando una fila
114
- individual tiene `reviewRequired: true` la salida se prefija con un aviso
115
- recordando que la tarea es tentativa hasta que un humano la valide; en
116
- listados, cada fila pendiente se anota inline y el footer cuenta cuántas
117
- hay pendientes.
118
-
119
- ### Changed
120
- - Las descripciones de `list_tasks` y `get_task` (visibles en MCP/OpenAPI)
121
- ahora documentan el campo `reviewRequired` y la regla operativa: las
122
- tareas pendientes deben tratarse como tentativas, sin construir trabajo
123
- derivado encima.
124
-
125
- ## [0.1.0] — 2026-04-23
126
-
127
- Primera publicación pública en npm como
128
- [`@roilab/crm-cli`](https://www.npmjs.com/package/@roilab/crm-cli).
129
-
130
- ### Added
131
- - Flujo de dispositivo (OAuth-style) para login sin pegar API keys en disco.
132
- Tokens corto/largo con rotación (`crm_at_` / `crm_rt_`).
133
- - Sustantivos: `auth`, `task`, `comment`, `client`, `domain`, `backlink`,
134
- `change`, `scope`, `competitor`, `tag`, `member`, `recall`, `search`,
135
- `inbox`, `review`, `doctor`.
136
- - Flag `--shadow` para forzar que una escritura aterrice como propuesta
137
- pendiente de revisión humana.
138
- - Flag `--wait-for-approval --timeout <dur>` para bloquear hasta decisión
139
- humana.
140
- - `crm recall <url>` como memoria cross-entity antes de crear trabajo nuevo.
141
- - Comprobación diaria de versión contra el registro de npm; `crm doctor`
142
- avisa cuando hay una versión más reciente. Nudge en stderr, sin bloquear
143
- stdout JSON.
144
- - Todas las cadenas visibles en español.
1
+ # Changelog
2
+
3
+ Todos los cambios notables se documentan aquí. El formato sigue
4
+ [Keep a Changelog](https://keepachangelog.com/es/) y el versionado es
5
+ [SemVer](https://semver.org/lang/es/).
6
+
7
+ ## [Unreleased]
8
+
9
+ _Ningún cambio pendiente todavía._
10
+
11
+ ## [0.7.0] — 2026-05-18
12
+
13
+ ### Added
14
+
15
+ - **`crm chat send --file <path...>` / `crm chat reply --file <path...>`.**
16
+ Adjuntos en mensajes de chat. Bandera repetible para varios archivos;
17
+ el cliente rechaza localmente cualquier archivo > 10 MB y avisa por
18
+ stderr a partir de 2 MB. Mime types comunes (imágenes, PDF, Office,
19
+ texto/JSON/CSV/HTML, zip) se detectan por extensión; el resto cae a
20
+ `application/octet-stream` (aceptado por el server, renderizado como
21
+ ficha genérica en la UI). `--body` pasa a ser opcional cuando se
22
+ adjunta al menos un archivo. Subida en dos pasos:
23
+ `POST /chats/:id/uploads` → URL one-shot → `POST /chats/:id/messages`
24
+ con `attachments[]`.
25
+
26
+ ### Documentation
27
+
28
+ - **SKILL.md cubre toda la superficie 0.6.0+.** Añadidas secciones
29
+ de `chat` (read/get/thread/send/reply/react/dm/mark-read incl.
30
+ `--file`) y `skill` autoring (revisions, revision, create, set,
31
+ archive, restore — las nuevas en 0.6.0 estaban sin documentar).
32
+ Anotada la restricción del mini-`--jq` (no soporta `|` / `\(.x)` /
33
+ proyección) y reemplazados los ejemplos rotos por equivalentes con
34
+ `jq` post-pipe. Quitadas dos referencias obsoletas a "v2 CLI flag"
35
+ (`--outcome`, `crm change create`) que prometían comandos
36
+ inexistentes. Recordatorio explícito de que `--no-review` ya se
37
+ respeta end-to-end desde 0.6.0.
38
+ - **SURFACE.txt** — actualizado el ejemplo de `bulk-approve` para no
39
+ usar interpolación mini-jq.
40
+
41
+ ## [0.6.0] — 2026-05-18
42
+
43
+ ### Added
44
+
45
+ - **`crm chat get <threadId> [--message-limit n]`.** Devuelve el hilo
46
+ completo (metadata + participantes + `unreadCount` + últimos mensajes)
47
+ en una sola llamada. Mapea a `GET /chats/:id`. Cierra el hueco entre
48
+ `chat list` (sólo metadata) y `chat read` (sólo mensajes paginados).
49
+ - **`crm skill {revisions,revision,create,set,archive,restore}`.** Cierra
50
+ la superficie de gestión de skills en Convex:
51
+ - `skill revisions <slug>` → historial publicado (`GET /skills/:slug/revisions`).
52
+ - `skill revision <id>` → revisión inmutable completa
53
+ (`GET /skills/revisions/:id`).
54
+ - `skill create --slug --name --description --category [--kind --tag
55
+ --visibility --body --frontmatter]` → crea draft
56
+ (`POST /skills`). La primera publicación va con `skill push <slug>
57
+ --publish`.
58
+ - `skill set <slug> [--name --description --category --kind --tag
59
+ --visibility]` → patch de metadatos
60
+ (`PATCH /skills/:slug`). El cuerpo y frontmatter se editan con
61
+ `skill push` — `set` cubre sólo los campos del registro.
62
+ - `skill archive <slug>` / `skill restore <slug>` → ocultar / restaurar
63
+ (`POST /skills/:slug/archive` y `/restore`).
64
+
65
+ ### Fixed
66
+
67
+ - **`task create --no-review` ahora aplica el flag.** Antes el CLI lo
68
+ enviaba pero el schema Zod de `create_task` no lo declaraba, así que
69
+ Zod lo descartaba antes de llegar a `apiGateway.createTask`. Añadido
70
+ `reviewRequired` al schema y a `GATEWAY_ONLY_FIELDS` para que la ruta
71
+ de cookies Better-Auth siga limpiando el campo (la mutación directa
72
+ `api.tasks.create` no lo acepta — `actorType` decide el valor server-
73
+ side para callers no-agente).
74
+
75
+ ## [0.5.0] — 2026-05-17
76
+
77
+ ### Added
78
+
79
+ - **`crm rank {list,get,add,tag,archive,restore,delete}`.** CLI completo
80
+ para keywords del rank tracker. Reads cubren filtros `--domain` /
81
+ `--country` / `--device` / `--state` / `--unranked` / `--canibalised`
82
+ / `--search`; `--ids-only` deja pipear a las operaciones bulk.
83
+ Writes: `add` importa keywords desde `--text` / `--file` / `--stdin`;
84
+ `tag` acepta `--add` / `--remove` / `--replace`; `archive`,
85
+ `restore` y `delete` operan en lotes hasta 500 ids. Todos los bulk
86
+ aceptan ids posicionales, `--stdin` (newline / coma / espacio) o
87
+ `--ids-from-file`. Endpoints REST equivalentes:
88
+ `/api/v1/rank-tracker/keywords*`. Requiere los scopes
89
+ `rank-tracker:read` / `rank-tracker:write` (concedidos por defecto
90
+ a owner / admin / member; nunca a roles cliente).
91
+
92
+ ## [0.4.0] — 2026-05-12
93
+
94
+ ### Added
95
+
96
+ - **Task participants completos.** `task create` y `task update` aceptan
97
+ `--collaborator <id...>` (followers — notificados pero no responsables) además
98
+ de `--assignee`. También cierra otros huecos del registro REST que el CLI no
99
+ exponía: `--start <date>`, `--completion-strategy <all|any|manual>`,
100
+ `--board <id>` (mover de tablero en `update`), y `--tag <id...>` /
101
+ `--assignee <id...>` en `update`. Equivalente Convex: el campo
102
+ `tasks.collaborators` ya existía pero no estaba enrutado por el gateway ni
103
+ el endpoint REST — ahora sí.
104
+ - **`crm backlink {pending,verify,reject,rejection-report}`.** Cubre el flujo
105
+ humano de QA de backlinks. `reject` requiere `--reason` estructurado del
106
+ catálogo (`spammy_source | wrong_anchor | wrong_target | nofollow_unexpected
107
+ | dead_on_arrival | duplicate | policy_violation | other`).
108
+ - **`crm review feedback [--retryable-only]`.** Loop de iteración del agente
109
+ documentado en `SKILL.md`: lee tus propuestas rechazadas con `rejectionReason`
110
+ + `allowRetry` para re-proponer. Mapea a `GET /reviews/feedback`.
111
+ - **`crm review bulk-approve` / `bulk-reject`.** Aprueba o rechaza hasta 100
112
+ propuestas en una sola llamada. Items por stdin (NDJSON o tokens `kind:id`),
113
+ típico encadenado: `crm review list --jq '.data[] | "\(.kind):\(.id)"' | crm
114
+ review bulk-approve`.
115
+ - **`crm report {create,update,delete}`.** Schedules CRUD. Body JSON por
116
+ `--body <json | @path | ->` para no aplanar la unión scope/cadence/approval
117
+ en flags mutuamente dependientes.
118
+ - **`crm access {request,list,approve,deny}`.** Namespace canónico para
119
+ solicitudes de acceso vía chat. Las variantes antiguas bajo `crm task
120
+ {request-access,list-access-requests,approve-access,deny-access}` siguen
121
+ funcionando con un aviso `[DEPRECATED]` en stderr; se retiran en la
122
+ próxima release mayor.
123
+ - **`crm commands`.** Dump JSON del árbol completo del CLI (verbos, args,
124
+ flags) para que los agentes introspeccionen la superficie sin parsear
125
+ `--help`. Devuelve `{ data: { tree, flat } }`.
126
+ - **`crm dashboard summary --start --end`.** Time-series agregado de todo el
127
+ workspace para overviews. Mapea a `GET /dashboard/summary`.
128
+ - **`crm domain get <id>`.** Single-domain fetch con tags + propiedades
129
+ resueltas. Nuevo endpoint `GET /domains/:id` en el registro REST.
130
+ - **`crm time list-task <taskId>`.** Lista entradas de tiempo de una tarea
131
+ sin filtro por fecha. Mapea a `GET /tasks/:taskId/time-entries`.
132
+
133
+ ### Changed
134
+
135
+ - **`task update --client-visible` ahora es simétrico.** Antes era
136
+ `--client-visible <bool>` (string parseado). Ahora se usan los flags
137
+ booleanos de commander: `--client-visible` para marcar visible,
138
+ `--no-client-visible` para marcar interna. Omitir el flag deja la
139
+ visibilidad sin cambios. `task create --client-visible` ya era el flag
140
+ booleano correcto.
141
+ - **Notificación de actualización a usuarios — dos canales nuevos:**
142
+ - **Cache auto-refresh en segundo plano.** Al ejecutar cualquier comando
143
+ el CLI lanza un hijo *detached* (no bloquea el foreground) que
144
+ refresca `~/.config/crm/cache.json` contra `registry.npmjs.org` cuando
145
+ está caducada (>24h) o no existe. Antes solo `crm doctor` refrescaba;
146
+ ahora cualquier invocación cierra el hueco "nunca corro doctor". El
147
+ nudge instantáneo (`maybeNudgeFromCache`) sigue siendo síncrono y sin
148
+ red — el hijo solo escribe la cache para la siguiente invocación.
149
+ - **`User-Agent` + `X-Crm-Cli-Version` en cada llamada HTTP.** El
150
+ servidor compara contra `RECOMMENDED_CLI_VERSION` y `MIN_CLI_VERSION`
151
+ en `src/lib/cli-version-policy.ts`. Si el caller va por detrás, estampa
152
+ `meta.cliUpdate: { current, recommended, severity }` en cada envelope
153
+ (tanto éxito como error, también en replays idempotentes). El CLI lee
154
+ `meta.cliUpdate` y muestra un aviso por stderr una vez por proceso —
155
+ "soft" para upgrades recomendados, "ATENCIÓN" para versiones por
156
+ debajo del mínimo. Mecanismo controlado para forzar avisos sin esperar
157
+ a la TTL de cache de 24h.
158
+
159
+ ## [0.3.0] — 2026-05-04
160
+
161
+ ### Added
162
+ - `crm task preflight --title <t> [--url <u>] [--domain <id>]` — bundle de
163
+ un round-trip que un agente debe ejecutar **antes** de cualquier
164
+ `crm task create`. Devuelve seis secciones acotadas (≤5 items por
165
+ defecto): `similarTasks` (FTS de título re-rankeado por Jaccard +
166
+ recencia + bonus same-domain), `recall` (cuando pasas `--url` —
167
+ fan-out por URL como en `crm recall`, capeado a 10), `recentChanges`,
168
+ `urlScopedTasks` (tareas abiertas ya enlazadas a esa URL),
169
+ `recentBacklinks`, `openTaskCounts` del dominio y `hints[]` en
170
+ español. El `summary` del envelope prioriza la pista accionable
171
+ (duplicado → cargas en URL → similares → adelante).
172
+ Equivalente REST: `GET /tasks/preflight?title=…&url=…&domainId=…`.
173
+ - Skill bundle nuevo `task-preflight` (lazy) con árbol de decisión:
174
+ cuándo NO crear, cuándo cargar GSC/GA4 vivo después del preflight,
175
+ anti-patrones, ejemplo realista. Cárgalo sólo si el envelope deja
176
+ al agente en duda — el `summary` resuelve el 80% de los casos.
177
+
178
+ ### Changed
179
+ - `cli/SKILL.md` — la regla operativa #1 pasa de "always recall before
180
+ creating" a el **ritual obligatorio del preflight**. Documenta que no
181
+ hay que pre-crawlear con Screaming Frog para entender una URL puntual
182
+ (usa `WebFetch` 1-shot) y que GSC/GA4 vivos se llaman *después* del
183
+ preflight, no antes.
184
+ - `tool-routing` añade fila para "decidir si crear tarea" → apunta a
185
+ `task-preflight` antes de cargar cualquier otro skill.
186
+
187
+ ## [0.2.0] — 2026-05-01
188
+
189
+ ### Added
190
+ - `crm task list --review-pending` y `--review-acked` para filtrar tareas
191
+ según `reviewRequired`. Útil para que un agente encuentre rápidamente las
192
+ tareas que él mismo creó y siguen pendientes de validación humana.
193
+ Equivalente REST: `GET /tasks?reviewRequired=true|false`.
194
+ - Banner `⚠ REVISAR` en el formato `--markdown`/`--styled`: cuando una fila
195
+ individual tiene `reviewRequired: true` la salida se prefija con un aviso
196
+ recordando que la tarea es tentativa hasta que un humano la valide; en
197
+ listados, cada fila pendiente se anota inline y el footer cuenta cuántas
198
+ hay pendientes.
199
+
200
+ ### Changed
201
+ - Las descripciones de `list_tasks` y `get_task` (visibles en MCP/OpenAPI)
202
+ ahora documentan el campo `reviewRequired` y la regla operativa: las
203
+ tareas pendientes deben tratarse como tentativas, sin construir trabajo
204
+ derivado encima.
205
+
206
+ ## [0.1.0] — 2026-04-23
207
+
208
+ Primera publicación pública en npm como
209
+ [`@roilab/crm-cli`](https://www.npmjs.com/package/@roilab/crm-cli).
210
+
211
+ ### Added
212
+ - Flujo de dispositivo (OAuth-style) para login sin pegar API keys en disco.
213
+ Tokens corto/largo con rotación (`crm_at_` / `crm_rt_`).
214
+ - Sustantivos: `auth`, `task`, `comment`, `client`, `domain`, `backlink`,
215
+ `change`, `scope`, `competitor`, `tag`, `member`, `recall`, `search`,
216
+ `inbox`, `review`, `doctor`.
217
+ - Flag `--shadow` para forzar que una escritura aterrice como propuesta
218
+ pendiente de revisión humana.
219
+ - Flag `--wait-for-approval --timeout <dur>` para bloquear hasta decisión
220
+ humana.
221
+ - `crm recall <url>` como memoria cross-entity antes de crear trabajo nuevo.
222
+ - Comprobación diaria de versión contra el registro de npm; `crm doctor`
223
+ avisa cuando hay una versión más reciente. Nudge en stderr, sin bloquear
224
+ stdout JSON.
225
+ - Todas las cadenas visibles en español.
package/SKILL.md CHANGED
@@ -51,7 +51,7 @@ Flags (mutually exclusive except `--jq`):
51
51
  - `--ids-only` — one id per line.
52
52
  - `--count` — a single integer.
53
53
  - `--markdown` — human preview (NOT JSON, do not parse).
54
- - `--jq <expr>` — tiny filter: `.a`, `.a.b`, `.a[]`, `.a[].b`, `.`. Full jq is intentionally not bundled.
54
+ - `--jq <expr>` — tiny path filter: `.a`, `.a.b`, `.a[]`, `.a[].b`, `.a[0]`, `.`. **Pipes (`|`), string interpolation (`\(.x)`), and object/array projection (`{…}`, `[.]`) are NOT supported** — pipe through real `jq` after `--quiet` if you need those.
55
55
 
56
56
  Errors **always** appear on stderr with full envelope, bypassing `--jq`. Exit codes:
57
57
 
@@ -98,13 +98,14 @@ Errors **always** appear on stderr with full envelope, bypassing `--jq`. Exit co
98
98
  --body "Chose to revert meta title; A/B showed −8% CTR in 14d"
99
99
  ```
100
100
 
101
- 3. **Write an outcome when completing tasks**. The UI shows this as a pinned summary:
101
+ 3. **Mark completed tasks explicitly**. Pair the status change with a `--kind decision` comment that explains the outcome — that's what the UI surfaces as the closing summary:
102
102
  ```bash
103
103
  crm task update tsk_abc --status done
104
- # Then: PATCH /tasks/tsk_abc with outcome field (v2 CLI flag: `--outcome`)
104
+ crm comment create --task tsk_abc --kind decision \
105
+ --body "Cerrado: H1 reemplazado, A/B +12% CTR a 14d (ver crm change list)"
105
106
  ```
106
107
 
107
- 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).
108
+ 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.)
108
109
 
109
110
  **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`).
110
111
 
@@ -255,6 +256,24 @@ Updating a task's description with a new `@mention` only fires for the
255
256
  You can safely edit a description that already references people without
256
257
  re-pinging them.
257
258
 
259
+ ## Adjuntar archivos al chat
260
+
261
+ `crm chat send` y `crm chat reply` aceptan `--file <ruta>` (repetible).
262
+ El CLI sube cada archivo en dos pasos (URL firmada → `POST` directo a Convex
263
+ storage) y luego envía el mensaje con la lista de adjuntos. Límites:
264
+
265
+ - **Máx 10 MB por archivo** — el CLI rechaza localmente antes de tocar la red.
266
+ - **Aviso a partir de 2 MB** en stderr (`[AVISO] ... la subida puede tardar.`).
267
+ - MIME se sniffa por extensión; lo desconocido viaja como `application/octet-stream`,
268
+ que el servidor acepta y la UI renderiza como tarjeta genérica.
269
+ - `--body` es opcional si pasas `--file` (mensajes sólo-archivos están
270
+ permitidos).
271
+
272
+ ```bash
273
+ crm chat send "$TID" --body "captura del 404" --file ./bug.png
274
+ crm chat reply <msgId> --thread "$TID" --file ./report.pdf --file ./logs.txt
275
+ ```
276
+
258
277
  ## Common recipes
259
278
 
260
279
  ```bash
@@ -270,14 +289,15 @@ crm task create \
270
289
  --description "Current H1 buries the value prop; replace with 'Plans that scale with you'." \
271
290
  --idempotency-key 01HY8X...
272
291
 
273
- # Log a change event after shipping (via a future `crm change create` in v2)
274
- # For now, the POST /domains/:id/changes endpoint is the fastest path.
292
+ # Log change events after shipping — no CLI verb yet; hit the REST endpoint
293
+ # directly: POST /api/v1/domains/<domainId>/changes (autogenerates an
294
+ # idempotency key per call; same envelope contract).
275
295
 
276
296
  # Search across everything
277
297
  crm search "meta title" --kind change --domain dom_xyz --limit 5
278
298
 
279
299
  # Live provider-API queries (tokens stay on the server)
280
- crm integration list --jq '.data[] | {id:._id, provider, services}'
300
+ crm integration list --quiet | jq -r '.[] | "\(._id) \(.provider) \(.services|join(","))"'
281
301
  crm gsc query --property prop_abc --dimension page \
282
302
  --filters "page contains /blog/" --start 2026-03-01 --end 2026-04-01 --limit 50
283
303
  crm ga4 query --property prop_abc --start 2026-03-01 --end 2026-04-01 \
@@ -285,11 +305,33 @@ crm ga4 query --property prop_abc --start 2026-03-01 --end 2026-04-01 \
285
305
  crm bing query --property prop_bing --start 2026-03-01 --end 2026-04-01
286
306
  crm integration sync --property prop_abc # forces fresh ingestion (15m cooldown)
287
307
 
288
- # Agency skills — pull the library so Claude Code picks them up
289
- crm skill list --category local-seo --quiet
290
- crm skill pull --all # writes .claude/skills/<slug>/SKILL.md
291
- crm skill update # refresh any outdated skill
292
- crm skill diff auditoria-seo-local # local vs remote state
308
+ # Agency skills — read the library + sync it to disk so Claude Code picks it up
309
+ crm skill list --category local-seo --quiet # all published in category
310
+ crm skill show auditoria-seo-local # metadata + revision id
311
+ crm skill revisions auditoria-seo-local # publish history
312
+ crm skill revision <revisionId> # single immutable revision
313
+ crm skill pull --all # writes .claude/skills/<slug>/SKILL.md
314
+ crm skill update # refresh any outdated skill
315
+ crm skill diff auditoria-seo-local # local vs remote state
316
+
317
+ # Agency skills — authoring (owner / admin / member with skills:write)
318
+ crm skill create --slug my-playbook --name "Mi playbook" \
319
+ --description "Cuándo y cómo aplicarlo" --category content
320
+ crm skill set my-playbook --visibility staff_only # metadata-only PATCH
321
+ crm skill push my-playbook --note "primera revisión" --publish # body+frontmatter
322
+ crm skill archive my-playbook # hide from library
323
+ crm skill restore my-playbook # un-archive
324
+
325
+ # Chat — read threads, post messages, react, attach files (max 10 MB each)
326
+ crm chat list --scope client --client cli_abc
327
+ crm chat get <threadId> --message-limit 50 # metadata + recent msgs
328
+ crm chat read <threadId> --page-limit 50 --before <ms> # paginate backwards
329
+ crm chat send <threadId> --body "$(crm mention member luis) revisado"
330
+ crm chat send <threadId> --body "informe adjunto" --file ./audit.pdf --file ./serp.png
331
+ crm chat reply <messageId> --thread <threadId> --body "ok, mañana"
332
+ crm chat react <messageId> --emoji "👀" # toggle (re-run unreacts)
333
+ crm chat dm --member mem_xyz --title "1:1 review"
334
+ crm chat mark-read <threadId>
293
335
  ```
294
336
 
295
337
  ## Decision tree for analytics questions
@@ -368,11 +410,15 @@ Reasons are a closed catalog (`spammy_source | wrong_anchor | wrong_target | nof
368
410
  `crm review` supports bulk operations via stdin (NDJSON or `kind:id` tokens, ≤100 per call):
369
411
 
370
412
  ```bash
371
- # Approve every pending proposal from your key:
372
- crm review list --mine --quiet --jq '.[] | "\(.kind):\(._id)"' | crm review bulk-approve
413
+ # Approve every pending proposal from your key. The CLI's mini-jq only
414
+ # walks paths — it doesn't support `|` or string interpolation — so use
415
+ # real `jq` after `--quiet` for the projection:
416
+ crm review list --mine --quiet \
417
+ | jq -r '[.tasks[]|"task:"+.id, .comments[]|"comment:"+.id, .edits[]|"edit:"+.id] | .[]' \
418
+ | crm review bulk-approve
373
419
 
374
420
  # Reject many with one reason (allowRetry defaults to true):
375
- echo -e "task:tsk_a\ntask:tsk_b" | crm review bulk-reject --reason "Out of scope this quarter"
421
+ printf 'task:tsk_a\ntask:tsk_b\n' | crm review bulk-reject --reason "Out of scope this quarter"
376
422
  ```
377
423
 
378
424
  ## Escape hatches