claude-code-arcane 2.2.0 → 2.3.0

package/skills/freelance-proposal/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: freelance-proposal
+description: "Write an Upwork proposal that survives the list view and price it above your net floor rate: hook in the first two lines, proof instead of adjectives, fixed vs hourly, risk buffer and platform fee. Reviewed by a fresh-context agent before spending Connects. Triggers: escribir propuesta upwork, cover letter upwork, cuanto cobrar por este proyecto, bid, cotizar proyecto freelance, propuesta freelance."
+argument-hint: "[nota de aplicación | job-url]"
+category: "career"
+user-invocable: true
+allowed-tools: Read, Glob, Grep, Write, Edit, WebFetch, Task
+---
+
+# Upwork Proposal - Propuesta y bid
+
+Escribís la propuesta y le ponés precio. Dos cosas en una skill porque en Upwork van juntas: el bid es parte de la propuesta y una no se defiende sin la otra.
+
+Rutas relativas al career workspace (`--workspace`, env `CAREER_WORKSPACE`, o `./career-workspace/`).
+
+Oferta indicada: `$ARGUMENTS`
+
+## Precondición: el screen
+
+**No redactar una propuesta sin la nota de `/client-screen`.** Si no existe, pedirla y correr ese skill primero.
+
+Si el screen dio riesgo alto o `NO POSTULARSE` y el usuario quiere postularse igual, se puede - **pero se le dice qué falló y se registra en la nota** (regla 1 de `freelance-guardrails`). Los Connects son plata: gastarlos a ciegas es distinto de gastarlos con los ojos abiertos.
+
+## Inputs
+
+- **El job post completo** y la nota de `03-Aplicaciones/` con el screen.
+- **El perfil base** de `01-Perfiles/` - de ahí salen la prueba y el **piso de tarifa neto**.
+- **La estimación** de `/estimate` si el alcance es grande.
+- Trabajos previos comparables (`08-Contratos/` cerrados) para calibrar precio contra realidad, no contra deseo.
+
+## Parte 1 - La propuesta
+
+### Cómo la lee el cliente
+
+Tiene 30 propuestas en una lista y ve **las dos primeras líneas de cada una**. Todo lo que no esté ahí, no existe todavía. Esa es la única restricción de formato que importa.
+
+### Estructura
+
+1. **Dos primeras líneas (el 80% del trabajo).** Algo que solo se sabe habiendo leído *este* post: el problema real detrás del pedido, una observación técnica concreta, o el resultado que podés traer. Si la apertura serviría para cualquier otro trabajo del rubro, está muerta.
+2. **Prueba, 2-3 oraciones.** Un proyecto comparable con número o link. No adjetivos: "expert in React" es ruido, "migré un checkout de 40k usuarios a React, bajé el tiempo de carga 60%" es prueba.
+3. **Cómo lo harías, 3-4 puntos.** Suficiente para mostrar que ya lo pensaste, no tanto que regales la consultoría.
+4. **El precio, justificado.** Ver Parte 2. Un número suelto invita a regatear.
+5. **Una pregunta concreta** sobre el proyecto. Sin pregunta no arranca conversación, y demuestra que leíste el post.
+
+**150-300 palabras.** Arriba de 300 casi nunca se lee entera.
+
+### Requisitos explícitos del post
+
+Muchos posts piden algo puntual: empezar con una palabra clave, responder una pregunta específica, mandar un link. **Buscalo siempre y cumplilo.** Es descarte automático y es el error más barato de evitar.
+
+### Anti-patrones (cortar siempre)
+
+- "I have X years of experience in..." como apertura. El cliente no contrata experiencia, contrata la solución de un problema que ya tiene.
+- "Dear Sir/Madam", "I hope this message finds you well".
+- Recitar el perfil en prosa.
+- Adjetivos sin evidencia: passionate, detail-oriented, fast learner.
+- Frases que delatan plantilla o generación automática. Los clientes de Upwork las reconocen al instante y es la razón número uno de descarte.
+- Prometer plazos que no podés cumplir para ganar el contrato.
+
+## Parte 2 - El bid
+
+### El piso es neto
+
+El piso de tarifa de `01-Perfiles/` es **lo que te queda**, no lo que facturás. Upwork se queda una comisión, así que el bid tiene que cubrirla: con un piso de 40 USD/h y 10% de comisión, el bid mínimo es ~45.
+
+**Si el bid calculado queda abajo del piso, decilo fuerte y no lo maquilles.** El trabajo correcto ahí es no postularse o cotizar lo que corresponde y perder la oferta - no bajar el piso. Bajar la tarifa es la palanca más fácil de ejecutar y la más difícil de revertir: baja el techo de todos los contratos siguientes.
+
+### Fijo u hora
+
+| Elegí fijo cuando | Elegí hora cuando |
+|---|---|
+| El alcance está escrito y acotado | El alcance es exploratorio o va a cambiar |
+| Podés estimar con confianza media o alta | Hay dependencias del cliente que no controlás |
+| Querés capturar valor arriba de tus horas | El cliente pide "iremos viendo" |
+
+Alcance difuso + precio fijo es la combinación que más plata pierde. Si el screen marcó alcance difuso y el cliente insiste en fijo, el precio tiene que incluir el riesgo o el trabajo correcto es no tomarlo.
+
+### El cálculo
+
+1. Esfuerzo base de `/estimate`, en horas.
+2. **Buffer de riesgo** según lo que dijo el screen: alcance claro y cliente con historial, +15%; alcance difuso o cliente nuevo, +40% o más. El buffer no es grasa, es el precio de la incertidumbre que el cliente te transfiere.
+3. Horas no facturables del proyecto: reuniones, revisiones, ida y vuelta.
+4. Multiplicar por la tarifa objetivo (no por el piso: el piso es el mínimo, no la meta).
+5. Sumar la comisión de la plataforma.
+6. Comparar contra el presupuesto del cliente. Si no cierra, es dato para la decisión, no para bajar el número.
+
+Mostrar el desglose al usuario **antes** de escribirlo en la propuesta. Al cliente se le muestra el total y su razón, no la planilla.
+
+## Proceso
+
+1. Leer el post, el screen y el perfil. Verificar que el screen exista.
+2. Calcular el bid (Parte 2) y mostrar el desglose. Si queda abajo del piso, avisar y parar a decidir.
+3. Draftear la propuesta (Parte 1). Después cortar sin piedad todo lo genérico.
+4. **Review con `proposal-reviewer`** (contexto fresco): pasale inline el post, el borrador y el bid. Aplicar sus reemplazos exactos e incorporar lo que corresponda. Una sola ronda. El que escribió leyó el post entero y ya está convencido de su propio gancho; el cliente ve dos líneas.
+5. Con approval, guardar en la nota de `03-Aplicaciones/`, sección `## Propuesta`, con el bid y su justificación en `## Cotización`.
+6. Si el usuario quiere ensayar la llamada, ofrecer `discovery-call`.
+
+## Idioma
+
+En el idioma del post. Si el post está en inglés, la propuesta va en inglés aunque la charla sea en español.
+
+## Reglas
+
+- Nunca inventar experiencia, clientes, plazos ni métricas.
+- Nunca bidear abajo del piso neto sin decirlo explícitamente.
+- Nunca enviar la propuesta: se muestra y el usuario copia y manda (regla 4 de `freelance-guardrails`).
+- Nunca marcar `propuesta_enviada`: eso lo hace `/job-outcome` después del envío.
+- Sin guiones largos en el texto de la propuesta ni de las notas.
+
+## Handoff
+
+Pedí aprobación (approval) antes de escribir la propuesta en la nota. Propuesta READY cuando pasó el review y el bid está sobre el piso. El siguiente paso es enviarla a mano y correr `/job-outcome` para registrar el envío y el gasto de Connects; si el cliente responde, `discovery-call` para ensayar y después `/contract-and-proposal-writer` para el SOW.

package/skills/freelance-scan/SKILL.md

@@ -0,0 +1,196 @@
+---
+name: freelance-scan
+description: "Find and score freelance projects across public keyless sources with dedup between runs, plus market intel on what other freelancers charge. Triggers: buscar proyectos freelance, scan de ofertas, scorear ofertas freelance, corrida de busqueda freelance, que ofertas me convienen, cuanto cobran otros freelancers, tarifa de mercado."
+argument-hint: "[search | web | market | keys | sources | post pegado]"
+category: "career"
+user-invocable: true
+allowed-tools: Read, Glob, Grep, Bash, Write, Edit, WebFetch, WebSearch
+---
+
+# Freelance Scan - Encontrar y scorear proyectos
+
+Producís una **cola triageada** de proyectos: scoreados contra el perfil y el piso de tarifa, sin repetir lo que ya viste. No postulás nada acá - el objetivo es decidir dónde gastar el screen y el dinero de postularse.
+
+Rutas relativas al career workspace (`--workspace`, env `CAREER_WORKSPACE`, o `./career-workspace/`).
+
+Modo o búsqueda: `$ARGUMENTS`
+
+## De dónde salen las ofertas
+
+El script `scripts/freelance_search.py` (stdlib, sin dependencias) trae proyectos de fuentes **públicas y sin API key**. Eso es un requisito, no una casualidad: este skillset lo instala cualquiera, y una fuente que exige credenciales propias de cada usuario deja el skill roto para todos menos uno.
+
+```bash
+python .claude/skills/freelance-scan/scripts/freelance_search.py sources
+python .claude/skills/freelance-scan/scripts/freelance_search.py search --query "unity developer" --pages 4
+python .claude/skills/freelance-scan/scripts/freelance_search.py market --months 3
+```
+
+| Fuente | Alcance | Filtro freelance |
+|---|---|---|
+| **GetOnBrd** | LatAm y remoto | `modality` Freelance, filtrado del lado del cliente |
+| **Himalayas** | Remoto global | `employmentType` Contractor, filtrado del lado del cliente |
+
+**Las dos aceptan un parámetro de modalidad y lo ignoran.** Devuelven 200 y mandan full-time igual (se probaron 7 variantes de nombre en GetOnBrd y 4 en Himalayas). Y **la búsqueda de GetOnBrd ordena por relevancia, no filtra**: `query=unity` devuelve 21 páginas donde el fondo es SAP y COBOL. Por eso el filtro de modalidad *y* el de relevancia son del lado del cliente.
+
+El script reporta `yield_by_source` en cada corrida, y hay que mostrárselo al usuario:
+
+```
+{'getonbrd': {'scanned': 103, 'freelance': 0, 'freelance_pero_irrelevante': 9}}
+```
+
+Eso se lee así: se leyeron 103 ofertas, 9 eran freelance, ninguna tenía que ver con lo buscado. **`freelance_pero_irrelevante` alto con `freelance: 0` significa que ese nicho no existe hoy en esa fuente** - no que la corrida falló. Decirlo explícitamente evita que el usuario repita la búsqueda pensando que se rompió algo.
+
+Rendimiento medido: GetOnBrd ~10 freelance cada 200 escaneados antes del filtro de relevancia; Himalayas ~28 cada 120.
+
+El match es por **límite de palabra**, no substring: en este dominio `go`, `ux`, `ai` y `qa` son búsquedas legítimas, y por substring `ux` matchearía dentro de "Linux" y `go` dentro de "Django". Costo aceptado y testeado: buscar `script` ya no encuentra "JavaScript". Los términos con símbolos (`c#`, `.net`, `node.js`, `react native`) caen a substring.
+
+### Expansión por sinónimos
+
+**Nadie titula una oferta "ecommerce".** La titula "Shopify". Buscar por categoría escondía trabajo real, medido sobre el pool completo:
+
+| Buscás | Sin expansión | Con expansión |
+|---|---|---|
+| `website` | 0 | 7 |
+| `backend` | 1 | 6 |
+| `ecommerce` | 0 | 1 (el Shopify que estaba ahí) |
+| `frontend` | 1 | 2 |
+| `go` | 0 | 1 (la oferta dice "Golang") |
+
+El mapa está en `SYNONYMS` dentro del script. Dos decisiones de diseño que importan:
+
+- **La expansión es unidireccional**: `ecommerce → shopify`, nunca al revés. Quien ya busca preciso no quiere que le infles los resultados.
+- **Se consulta el server una vez por término**, no solo se filtra distinto. El ranking de GetOnBrd depende de `query`, así que buscar "ecommerce" nunca trae el pool donde vive el de Shopify. El término del usuario se pagina hondo; cada sinónimo, una página. Tope de 6 términos extra, porque cada uno es una request.
+
+El output trae `terms_searched` y `synonyms_applied`: **mostráselos al usuario**, si no no entiende por qué una búsqueda de "ecommerce" le trajo Shopify. Con `--no-expand` se apaga.
+
+Si un nicho del usuario no está en el mapa, agregarlo es una línea - y conviene, porque el vocabulario de cada rubro es distinto.
+
+## Modo `web` - llegar a los marketplaces sin credencial
+
+Upwork, Workana, Freelancer.com, PeoplePerHour y Guru no tienen API pública. Pero **WebSearch sí los alcanza**, y la credencial es Claude Code, que ya tiene todo el que instaló el perfil.
+
+### Cómo se corre
+
+Disparar **varias `WebSearch` en un solo turno** (en paralelo, no una tras otra), combinando plataforma y término del stack del usuario:
+
+```
+WebSearch  allowed_domains: ["upwork.com"]     query: "<stack> freelance project hourly contract"
+WebSearch  allowed_domains: ["workana.com"]    query: "proyecto <stack> desarrollo freelance"
+WebSearch  allowed_domains: ["freelancer.com", "peopleperhour.com", "guru.com"]
+```
+
+Después pasar **todas** las URLs por el triage, que es la parte determinista:
+
+```bash
+python .claude/skills/freelance-scan/scripts/freelance_search.py triage \
+  --url "https://..." --url "https://..."
+```
+
+Devuelve `postings` (lo único que vale abrir), `descartados_landing` y `sin_clasificar`.
+
+### Por qué el triage no es opcional
+
+Medido sobre una corrida real: **de 13 URLs, 3 eran ofertas.** Las otras 10 eran landings de "Hire Golang developers", tablas de tarifas, gigs del Project Catalog y páginas de búsqueda. Sin filtrar, la cola es mitad basura y el usuario deja de mirarla.
+
+### Los tres límites, y hay que decirlos
+
+1. **La fecha no está verificada.** El índice no filtra por recencia: en la prueba real apareció una oferta de Upwork **posteada en 2021**. Siempre avisar que hay que mirar la fecha al abrir.
+2. **No se puede leer la oferta.** `WebFetch` devuelve **403 en todas** estas plataformas, incluso en páginas de proyecto individuales. Presupuesto, cantidad de propuestas y reputación del cliente requieren que el usuario abra el link.
+3. **El resumen de la búsqueda no es dato.** Es un modelo leyendo varias páginas; puede mezclar detalles de dos ofertas.
+
+Por eso este modo entrega **links para abrir**, no filas para el registro. Nunca guardar en `seen_jobs.json` una oferta que vino de acá con fecha o presupuesto sin confirmar: un dato inventado en el registro contamina todas las decisiones que se apoyan en él.
+
+## Modo `keys` - las fuentes que piden credencial propia
+
+```bash
+python .claude/skills/freelance-scan/scripts/freelance_search.py keys
+```
+
+Lista qué fuentes necesitan API key, **cómo conseguir cada una**, y si está configurada en esta máquina.
+
+**Upwork** tiene adaptador escrito. Se pide la key desde el API Center de la cuenta (freelancer o cliente, cualquier plan, sin cuenta de empresa) y contestan por mail en ~1 semana. Con `UPWORK_ACCESS_TOKEN` en el entorno, `search` la suma sola a la corrida y trae presupuesto, tarifa horaria y reputación del cliente, que es justo lo que el modo `web` no puede ver.
+
+Sin la variable puesta **no se intenta y se avisa**, en vez de fallar en cada corrida hasta que el usuario aprenda a ignorar los errores.
+
+Lo que ni con key se puede: **enviar propuestas**. Upwork no expone mutation para postularse ni para gastar Connects, a propósito, contra el auto-bidding. Postularse sigue siendo a mano siempre.
+
+**Nunca scrapear ninguna plataforma ni sugerir herramientas que lo hagan.** Donde el `robots.txt` opina, opina en contra: PeoplePerHour prohíbe las URLs con filtros y Guru prohíbe `/api/`. Detalle por plataforma con los códigos medidos: `references/platforms.md`.
+
+## Scoring
+
+Cada oferta recibe un `match_score` 0-100. Tres componentes, y el tercero es el que la mayoría ignora:
+
+### 1. Fit técnico (0-40)
+
+Cuánto de lo que piden cubrís con evidencia real del perfil. Must-haves cubiertos pesan; nice-to-haves suman poco. Un must-have que no cubrís no se compensa con tres nice-to-haves.
+
+### 2. Viabilidad económica (0-40)
+
+El presupuesto contra tu piso neto, estimando el esfuerzo real del alcance descrito.
+
+- Presupuesto que no llega al piso → **máximo 10 en este componente**, sin importar lo lindo que sea el proyecto.
+- Presupuesto sin especificar → no asumas que es bueno. Puntuá con la incertidumbre y marcalo.
+
+### 3. Probabilidad de que exista de verdad (0-20)
+
+Una parte importante de las ofertas de marketplace no termina contratando a nadie. Señales de que esta sí:
+
+- Cliente con pago verificado y contrataciones previas
+- Oferta reciente y con pocas propuestas todavía
+- Post específico, escrito por alguien que sabe lo que pide
+- Cliente que respondió preguntas en el propio post
+
+Señales contrarias: hire rate bajo con muchos posts, oferta vieja con decenas de propuestas, post genérico reutilizado.
+
+### Umbrales
+
+| Score | Acción |
+|---|---|
+| 70+ | Cola de screen: correr `/client-screen` |
+| 50-69 | Segunda vuelta: solo si la cola alta está vacía |
+| < 50 | Descartar y registrar el motivo en el estado de dedup |
+
+Los umbrales se documentan en la corrida. Si el usuario los quiere mover, se mueven - explícitamente, no por acomodo.
+
+## Modo `market` - qué cobran los demás
+
+El hilo mensual de Hacker News "Ask HN: Freelancer? Seeking freelancer?" **no es una fuente de trabajo**: medido sobre 6 meses hay 113 freelancers ofreciéndose contra 2 ofertas. Pero eso mismo lo vuelve la mejor fuente gratuita de otra cosa: **cómo se posiciona y cuánto cobra gente con tu perfil**.
+
+`market` devuelve los perfiles, las tarifas que mencionan (con la cita textual, sin inventar números), y un resumen con **n, mínimo, mediana y máximo por unidad**.
+
+**Solo ~3% de los perfiles declara una tarifa parseable**: en la corrida de 6 meses fueron 3 tarifas sobre 119 perfiles (mediana 100 USD/hora). Siempre reportar el `n` al usuario - una mediana sobre 3 datos orienta, no decide. Los precios por paquete ("75-150 USD un diagnóstico") no entran al resumen a propósito: no son tarifa horaria y mezclarlos ensucia la mediana.
+
+Sirve para dos decisiones concretas: el piso de tarifa que fija `/freelance-hunt setup` y usa `/freelance-profile`, y el bid de `/freelance-proposal`. Un tercer uso, menos obvio y bastante útil: leer cómo escriben su one-liner los que cobran más.
+
+## Dedup entre corridas
+
+Mismo mecanismo y mismo archivo que `/job-scrape`: `<workspace>/tools/job_scraper/seen_jobs.json`. Si `+job-hunt` está instalado, el estado es compartido y no hay dos archivos.
+
+Claves: URL canónica sin parámetros de tracking, y `job_key` = `slug(cliente)|slug(titulo)`. Matching blando (mismo cliente + títulos parecidos) es **warning**, nunca dedup automático.
+
+Flujo unidireccional: `seen_jobs` → nota → dashboard, nunca de vuelta. Playbook completo: `../job-scrape/references/dedup-playbook.md` si está instalado, o `references/dedup.md`.
+
+Reposteos: es común que un cliente cierre y republique la misma oferta. Si el `job_key` matchea una entrada `descartado`, avisar que ya se descartó antes y por qué, en vez de volver a triagearla de cero. Un cliente que republica cinco veces sin cambiar el presupuesto es en sí una señal para `/client-screen`.
+
+## Proceso
+
+1. **Cargar el estado de dedup.** Validar que las entradas `nota_creada` apunten a notas existentes; reportar las rotas.
+2. **Obtener las ofertas**: corrida del script, y/o las que el usuario pegue de plataformas cerradas.
+3. **Dedupear.** Reportar cuántas se filtraron, para que se vea que el mecanismo trabaja.
+4. **Scorear** las nuevas con los tres componentes. Mostrar la tabla en el chat: título, cliente, presupuesto, score y los tres subscores. Mostrar también el `yield_by_source` de la corrida.
+5. **Triagear** con approval del usuario: qué pasa a screen, qué queda en segunda vuelta, qué se descarta y por qué.
+6. **Registrar** en `seen_jobs.json`. Crear nota en `03-Aplicaciones/` (template `Propuesta`, `tipo: freelance`, `estado: interesado`) solo para las que pasan a screen - el motivo de descarte vive en el estado de dedup, no en una nota.
+
+## Reglas
+
+- **Nunca inventar ofertas, presupuestos ni datos de clientes.** Todo sale del post real o del script.
+- **Nunca scrapear** Upwork, Freelancer.com, Fiverr ni ninguna plataforma cuyos términos lo prohíban, ni sugerir herramientas que lo hagan.
+- **Nunca prender por defecto una fuente que exija credenciales por usuario.** Rompe el skill para todos los que instalen el perfil menos uno. Va en `KEYED_SOURCES`: se activa sola si la variable de entorno está, y si no, `keys` explica cómo conseguirla.
+- **Nunca guardar en el registro un dato que vino del modo `web` sin confirmar.** Fecha y presupuesto ahí no están verificados; escribirlos como si lo estuvieran envenena todas las decisiones posteriores.
+- Un presupuesto abajo del piso no se "compensa" con entusiasmo por el proyecto.
+- En `market`, nunca reportar una mediana sin su `n`.
+- Sin guiones largos en las notas. No crear notas para ofertas que no pasan el umbral.
+
+## Handoff
+
+Corrida COMPLETE cuando la cola quedó triageada y el estado de dedup actualizado. El siguiente paso es `/client-screen` sobre la primera de la cola alta. Si la corrida trajo poco o nada usable varias veces seguidas, el problema es el targeting: corré `/freelance-pipeline`.

package/skills/freelance-scan/references/dedup.md

@@ -0,0 +1,35 @@
+# Dedup entre corridas de /freelance-scan
+
+Si `+job-hunt` está instalado, la fuente de verdad es `../job-scrape/references/dedup-playbook.md` y el archivo de estado es **el mismo**: no se crean dos. Este archivo es el resumen autosuficiente para quien instaló `+freelance` solo.
+
+## Dónde vive
+
+`<workspace>/tools/job_scraper/seen_jobs.json`, no entre las notas: es dato de máquina, y el vault de Obsidian no debería indexarlo.
+
+## Matriz de fuente de verdad
+
+| Dato | Fuente de verdad | Quién escribe |
+|---|---|---|
+| "Ya vi esta oferta" + triage + descartes pre-nota | `seen_jobs.json` | `/freelance-scan` |
+| Estado del pipeline, `match_score` definitivo | Frontmatter de la nota en `03-Aplicaciones/` | `/client-screen` crea; `/job-outcome` actualiza |
+| Vista humana de la cola | `00-Dashboard.md` | Derivado de las notas |
+
+El flujo es **unidireccional**: `seen_jobs` → nota → dashboard. Cuando una entrada pasa a `nota_creada` se congela y conserva solo el puntero a la nota; el pipeline sigue en la nota y nunca se sincroniza de vuelta. Por eso `propuesta_enviada` no existe en este archivo.
+
+## Claves de dedup
+
+1. **URL canónica**: sin parámetros de tracking (`utm_*`, referidos), reducida al identificador de la oferta.
+2. **`job_key`** = `slug(cliente)|slug(titulo)`: lowercase, sin acentos ni puntuación, sin sufijos legales (inc, llc, sa), sin calificadores del título entre paréntesis ("(remote)", "(urgent)"). Detecta la misma oferta con URLs distintas.
+3. **Matching blando** (mismo cliente + alto solapamiento de tokens del título) es **warning**, nunca dedup automático: un cliente puede tener dos proyectos parecidos y legítimos.
+
+## Reposteos: el caso propio de Upwork
+
+Es común que un cliente cierre una oferta y la vuelva a publicar, a veces varias veces. Con URL nueva, la URL canónica no alcanza - lo detecta el `job_key`.
+
+Cuando un `job_key` matchea una entrada en `descartado`, **no volver a triagear de cero**: avisar que ya se descartó antes y por qué, y dejar que el usuario decida si algo cambió (presupuesto corregido, alcance aclarado). Un cliente que republica la misma oferta cinco veces sin cambiar el presupuesto es en sí una señal para `/client-screen`.
+
+## Mantenimiento
+
+- **Punteros rotos:** al arrancar, validar que toda entrada `nota_creada` apunte a una nota que existe. Reportar las rotas, no borrarlas en silencio.
+- **Poda (opt-in):** entradas `new` o `descartado` con `last_seen` de más de 90 días se pueden borrar, solo a pedido del usuario. Las `nota_creada` no se podan: son el historial contra el que se mide el pipeline.
+- **Primer run:** el archivo arranca con el esqueleto vacío. Si ya hay notas en `03-Aplicaciones/` con `tipo: freelance`, ofrecer backfillearlas como `nota_creada`.

package/skills/freelance-scan/references/platforms.md

@@ -0,0 +1,167 @@
+# Plataformas freelance: qué se puede consumir y qué no
+
+Estado verificado en agosto de 2026, corriendo las requests, no leyendo la documentación. Antes de agregar una fuente, verificar de nuevo: las plataformas cambian sin avisar.
+
+## El criterio, y por qué es estricto
+
+Este repo es público y lo instala cualquiera. Una fuente entra a la corrida automática solo si cumple **las tres**:
+
+1. **Sin API key ni registro.** Si cada usuario tiene que pedir credenciales, el skill funciona para uno y está roto para el resto.
+2. **Términos que permiten consumirla desde una herramienta local.** No alcanza con que técnicamente responda.
+3. **Tiene trabajo freelance de verdad**, no solo empleo remoto full-time.
+
+Que una API devuelva 200 no la habilita. Dos de las candidatas más recomendadas en internet fallan el punto 2 y quedaron afuera.
+
+## Incluidas
+
+### GetOnBrd (LatAm y remoto)
+
+`https://www.getonbrd.com/api/v0` · sin key · comparte API con `/job-scrape`
+
+- `/modalities` devuelve `1 Full time`, `2 Part time`, **`3 Freelance`**, `4 Internship`.
+- **El filtro de modalidad no existe del lado del servidor.** Se probaron `modality`, `modality_id`, `modalities`, `modality[]`, `filter[modality]`, `modality=freelance` y `job_modality`: las siete devuelven 200 y el mismo resultado sin filtrar (48 de 50 full-time). Hay que filtrar en el cliente.
+- **Usar `expand[]=company&expand[]=tags&expand[]=modality`.** Sin eso esos campos vienen como `{"data":{"id":...}}` y no hay nombre que mostrar. Lo aprendimos de `job-scrape/scripts/getonbrd_search.py`, que ya lo hacía.
+- **Trampa:** con `expand[]` el id de la modalidad llega como string `"3"`; sin expand, como int `3`. Comparar el id se rompe en silencio al cambiar los parámetros. Filtrar por `attributes.locale_key == "freelance"`.
+- Rendimiento medido: ~10 freelance cada 200 escaneados con `query=developer`.
+
+### Himalayas (remoto global)
+
+`https://himalayas.app/jobs/api` · sin key
+
+- `employmentType` toma los valores `Full Time` y **`Contractor`**.
+- **Tampoco filtra del lado del servidor:** se probaron `employmentType=Contractor`, en minúscula, `employment_type` y `type`. Las cuatro devuelven el mismo set mezclado y `totalCount` sin cambios (97.323).
+- **`limit` se topea en 20** aunque pidas más. Paginar con `offset`.
+- Rendimiento medido: ~28 contractor cada 120 escaneados. Sesgo a tener en cuenta: la cabeza del feed la domina una sola empresa de BPO con puestos no técnicos (transcripción, documentos, peritaje). Con filtro de query se acomoda, pero ese pool no es homogéneo y el usuario tiene que saberlo.
+
+## Solo para inteligencia de mercado, no para buscar trabajo
+
+### Hacker News: "Ask HN: Freelancer? Seeking freelancer?"
+
+`https://hn.algolia.com/api/v1` · sin key · 10.000 requests por hora
+
+El nombre engaña. Se midieron 6 hilos mensuales (marzo a agosto de 2026):
+
+| Categoría | Comentarios |
+|---|---|
+| Freelancers ofreciéndose (`SEEKING WORK`) | 113 |
+| Clientes buscando (`SEEKING FREELANCER`) | **2** |
+| Sin seguir la convención | 6 |
+
+Reproducible: `freelance_search.py market --months 6` devuelve ese conteo en `composition`.
+
+Como cola de trabajo no sirve. Como muestra de **cómo se posiciona y cuánto cobra gente con tu perfil**, es lo mejor que hay gratis. Por eso vive en el subcomando `market` y no en `search`.
+
+Rendimiento de la extracción de tarifas: **3 tarifas sobre 119 perfiles** (~3%), mediana 100 USD/hora. Poco, pero es dato real y con la cita textual al lado.
+
+Detalles de implementación: los comentarios vienen con HTML escapado (`github/user`), y los que no siguen la convención se clasifican como `unknown` a propósito - adivinar de qué lado están mete ofertas falsas en la cola, que es peor que omitirlas.
+
+## Excluidas, con motivo
+
+### RemoteOK
+
+Sus términos, que vienen **en el propio payload de la API**, exigen un backlink do-follow desde tu sitio mencionando RemoteOK como fuente, o suspenden el acceso.
+
+Un CLI local no tiene sitio web. No podemos cumplirlo, y usarlo igual haría que le suspendan la IP al usuario. Además, de 100 ofertas revisadas **ninguna** tenía tag `contract`, `freelance` ni `part-time`. Falla el punto 2 y el punto 3.
+
+### Remotive
+
+Mismo problema y más restricciones: backlink do-follow obligatorio, **máximo 4 requests por día**, datos con **24 horas de retraso** deliberado, y prohibición explícita de usar los datos para captar emails. Ofrecen una API privada de pago desde 5.000 USD al mes.
+
+Tiene `job_type` con valores `freelance` y `contract` reales, así que el punto 3 lo cumple. Los otros dos no.
+
+### Upwork
+
+- **API GraphQL** en `api.upwork.com/graphql` con OAuth 2.0. La key se pide desde el API Center de la cuenta (cualquier freelancer o cliente, cualquier plan - **no** hace falta cuenta de empresa) y según el propio soporte de Upwork **responden por mail en aproximadamente una semana**. El rechazo más común es data de cuenta incompleta.
+- **Sí tiene búsqueda de ofertas** (`marketplaceJobPostingsSearch`) entre las operaciones de lectura, junto con perfiles y contratos. Lo que no tiene es escritura de propuestas.
+- Límites si te la aprueban: 40.000 requests por día, 10 por segundo por IP.
+- **No hay mutation para enviar una propuesta ni para gastar Connects.** Está cerrado a propósito para frenar auto-bidding.
+- **Los RSS feeds murieron el 20 de agosto de 2024**, por la misma razón. Cualquier tutorial que los mencione está viejo.
+- Scrapear viola los ToS y es exactamente lo que la plataforma cerró.
+
+Por la aprobación manual por usuario **no entra a la corrida automática**: rompería el skill para todos menos quien tenga key. Si un usuario la consigue, puede escribir su propio adaptador siguiendo el patrón del script; el camino soportado es pegar la oferta a mano.
+
+### Freelancer.com
+
+API con OAuth 2.0 y credenciales por usuario (`Freelancer-Developer-OAuth-Client-Id`). No hay endpoint público de búsqueda de proyectos. Mismo problema estructural que Upwork.
+
+Hay wrappers de terceros en RapidAPI que dicen exponer la búsqueda sin credenciales. No los usamos: son intermediarios no oficiales, se caen sin aviso y su forma de obtener los datos no es auditable.
+
+### El resto de los marketplaces tipo Upwork
+
+Distinción que importa: GetOnBrd y Himalayas son **job boards** con una modalidad freelance. Upwork es un **marketplace**: el cliente publica, vos ofertás, hay Connects y escrow. Ninguna de las fuentes incluidas es un marketplace, y no es por falta de ganas.
+
+Probado en agosto de 2026, códigos reales:
+
+| Plataforma | Endpoint probado | Resultado |
+|---|---|---|
+| Workana (LatAm) | `/jobs.rss`, `/jobs.rss?language=es`, `/api/v1/projects` | 404 en las tres. No hay feed público |
+| Guru | `/rss/jobs/`, `api.guru.com` | 404 y DNS inexistente. Su `robots.txt` tiene `Disallow: /api/` explícito |
+| PeoplePerHour | `/freelance-jobs.rss` | 404. Su `robots.txt` tiene `Disallow: /*?`, o sea que las URLs de búsqueda con filtros están prohibidas |
+| Truelancer | `/api/projects` | 429 desde la primera request |
+| Freelancermap (DACH) | `/project-rss.xml`, `/api/v1/projects` | 404 y **401**: la API existe pero pide credenciales |
+| Malt (Europa) | `/api/missions` | **401**: misma historia |
+| Codeable, Twine | `/api/projects`, `/api/jobs` | 404 |
+
+Los dos 401 son el mismo problema estructural que Upwork: API real, credencial por usuario. No entran por el punto 1.
+
+El resto no expone nada, y donde el `robots.txt` habla, habla en contra: PeoplePerHour prohíbe justo las URLs con filtros y Guru prohíbe `/api/`. Sacar los proyectos de ahí sería scrapear contra la política declarada del sitio.
+
+**Conclusión para el diseño del perfil:** los marketplaces se usan a mano, en el navegador. El skill no busca ahí; ayuda con lo que pasa después de encontrar el posteo, que es donde se pierde la plata. Pegar la oferta a mano es el camino soportado, no un parche.
+
+Nota lateral útil: Lemon.io y Proxify (marketplaces con screening) publican sus búsquedas en Working Nomads, 21 de 50 avisos entre las dos. No se puede filtrar por modalidad ahí, pero dice algo sobre estrategia: pasar el screening de una de esas una vez rinde más que ofertar de a una.
+
+### Fiverr
+
+Modelo invertido: no te postulás a trabajos, publicás gigs y el comprador te encuentra. Los "Buyer Requests" ya no existen como los conocía la gente. No hay cola que scorear.
+
+### Toptal, Gun.io, Braintrust, Arc, Lemon.io
+
+Verticales con screening previo. No hay board público consumible; el acceso se gana pasando su proceso de admisión. Fuera del alcance de un scanner.
+
+### We Work Remotely
+
+Tiene RSS y funciona (`/remote-jobs.rss`, 100 items), pero **el feed de la categoría contract redirige a sí mismo**: `/categories/remote-contract-jobs.rss` devuelve 301 apuntando a la misma URL. Sin categoría de contract usable, el feed general es empleo full-time y no aporta a este perfil.
+
+### Arbeitnow
+
+Sin key y funciona. Tiene `job_types` con `Contract` (7 de ~100), pero es sobre todo ATS alemán y austríaco con puestos permanentes. Marginal: si en algún momento el usuario apunta al mercado DACH, vale agregarlo.
+
+### Jobicy
+
+`https://jobicy.com/api/v2/remote-jobs` · sin key · responde 200 y pagina bien.
+
+Pasa el punto 1 y, a diferencia de RemoteOK y Remotive, **pasa el punto 2**: su `friendlyNotice` pide crédito con link directo y que el botón de postularse apunte a la URL original del feed. Eso un CLI lo cumple, porque ya imprime fuente y URL, y no hay amenaza de suspensión.
+
+Falla el punto 3, que es el que importa: sobre 100 avisos, `jobType` dio **99 Full-Time y 1 Part-Time, ningún contract ni freelance**. Pedir `jobType=contract` devuelve HTTP 400, o sea que el valor no existe. Además el pool está dominado por Customer Support (25) y Sales (19), con solo 10 de Software Engineering.
+
+### Working Nomads
+
+`https://www.workingnomads.com/api/exposed_jobs/` · sin key · 50 avisos por llamada.
+
+**No tiene campo de tipo de contrato.** Las claves son `category_name`, `company_name`, `location`, `tags`, `title`, `url` y nada más, así que no hay forma de filtrar freelance: habría que adivinar por el título, y sobre 50 avisos solo 1 lo mencionaba.
+
+Detalle que igual vale registrar: la cabeza del feed la dominan Proxify (15 de 50) y Lemon.io (6), que son marketplaces de devs freelance. O sea que buena parte de esos puestos *son* contract en la práctica, pero eso es inferencia nuestra y no dato, y esas dos ya están descartadas por screening previo. Adivinar la modalidad desde el nombre de la empresa mete ruido en la cola, que es peor que no traerla.
+
+## El camino que sí llega a los marketplaces: WebSearch
+
+Medido en agosto de 2026. Es la excepción al problema de credenciales, porque la credencial es Claude Code mismo: todo el que instala el perfil ya la tiene.
+
+**Qué funciona.** `WebSearch` con `allowed_domains` devuelve URLs de proyectos reales en Upwork, Workana, Freelancer.com, PeoplePerHour y Guru. Tres búsquedas en paralelo en un turno traen candidatos de cinco plataformas a la vez, con títulos, y a veces con tarifa y stack en el resumen. Ejemplos que devolvió: `upwork.com/job/Golang-Developer_~0157b3a527d0809956/`, `workana.com/es/job/crear-tienda-shopify-ecommerce`.
+
+**Qué no funciona, y es la mitad importante.** `WebFetch` devuelve **403 en todo**: el listado de Workana, la búsqueda de Upwork y hasta las páginas de proyecto individuales que el buscador ya tenía indexadas. Cloudflare bloquea el fetcher. O sea que se puede descubrir la oferta pero **no leerla**: presupuesto, cantidad de propuestas, país del cliente y si tiene el pago verificado siguen requiriendo abrir el link vos.
+
+**Tres límites que hay que decir de frente:**
+
+1. **Frescura.** El índice no filtra por fecha. Una de las ofertas de Upwork que devolvió estaba **posteada en julio de 2021**. Para un marketplace donde una oferta de tres días ya está fría, es un problema serio.
+2. **Ruido de SEO.** Cerca de la mitad de los resultados no son ofertas: son landings de "Hire Golang developers", tablas de tarifas y gigs del Project Catalog. Hay que descartarlos por patrón de URL.
+3. **El resumen no es dato.** Lo que devuelve la búsqueda es un modelo resumiendo varias páginas: puede mezclar detalles de dos ofertas. Sirve como pista para abrir, no como campo para guardar.
+
+**Conclusión de diseño.** Da para descubrimiento y triage, no para screening ni para una cola confiable. Un skill que haga esto tiene que entregar links para abrir y decir explícitamente que la fecha no está verificada; guardar esos datos en el registro como si fueran ciertos sería peor que no tenerlos.
+
+## Si querés agregar una fuente
+
+1. **Correr la request y mirar el payload**, no la documentación. Las dos APIs incluidas mienten sobre sus propios filtros.
+2. **Leer los términos, incluido lo que venga dentro de la respuesta.** RemoteOK y Remotive ponen ahí las condiciones que las descalifican.
+3. **Medir el rendimiento freelance real** sobre una muestra y anotarlo acá. Una fuente con 2 ofertas útiles cada 500 no justifica la request.
+4. **Confirmar que no necesita credenciales por usuario.** Si las necesita, va como opt-in documentado, no en `SOURCES`.
+5. **Agregar los specs** en `tests/freelance/test_freelance_search.py` con un payload fijo. Nada de tests contra la red.