@ericrisco/rsc 0.1.57 → 0.1.59

package/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.1.57",
+  "version": "0.1.59",
   "counts": {
     "skills": 258
   },
@@ -1930,7 +1930,7 @@
     },
     {
       "id": "gamedev-physics",
-      "description": "Use when working with a game engine's physics — rigid bodies, colliders, collision layers/masks, character controllers, joints, forces vs impulses, raycasts/shapecasts, or when physics is unstable. Triggers: \\\"my character falls through the floor\\\", \\\"bullet tunnels through walls at high speed\\\", \\\"rigidbody jitters / vibrates / explodes\\\", \\\"objects that should collide pass through each other\\\", \\\"which collision layer and mask do I set\\\", \\\"kinematic vs dynamic body\\\", \\\"move_and_slide / CharacterBody\\\", \\\"AddForce vs impulse vs setting velocity\\\", \\\"physics in FixedUpdate or _physics_process\\\", \\\"slope and step detection\\\", \\\"trigger / Area overlap not firing\\\", Godot RigidBody/StaticBody/CharacterBody/Area, Unity Rigidbody/Collider/CharacterController, Unreal Chaos/collision presets. NOT rendering, materials, or visual jitter from shaders (use gamedev-shaders); NOT AI navigation, pathfinding, or navmesh (use gamedev-pathing).",
+      "description": "Use when working with a game engine's physics — rigid bodies, colliders, collision layers and masks, character controllers, joints, forces versus impulses, raycasts and shapecasts, or when a simulation is unstable (tunnelling, jitter, missed overlaps). Covers the Godot, Unity and Unreal equivalents. NOT rendering or shader-driven visual jitter (that is `gamedev-shaders`), NOT navigation, pathfinding or navmesh (that is `gamedev-pathing`).",
       "tags": [
         "physics",
         "collision",
@@ -2047,7 +2047,7 @@
     },
     {
       "id": "git-workflow",
-      "description": "Use when naming or scoping a branch, writing or fixing a commit message, untangling history (rebase vs merge vs squash), or cutting a versioned release — the portable git-convention layer that works on any repo. Triggers: 'name this branch', 'is this commit message conventional?', 'rebase or merge before the PR?', 'squash these wip commits into one', 'my git log is a mess', 'tag a release', 'write release notes', 'what version should this release be?', 'clean up history before review', 'limpia el historial antes del PR', '¿qué versión le toca a esta release?', 'deja los commits en formato convencional'. Covers Conventional Commits 1.0.0, SemVer tags, branch hygiene, force-push safety, and gh pr/release mechanics. NOT the I'm-done land-it decision and pre-ship checklist (that is ship), NOT setting up an isolated checkout before coding (that is worktrees), NOT CI/CD release automation in GitHub Actions (that is deployment).",
+      "description": "Use when naming or scoping a branch, writing or fixing a commit message, untangling history (rebase versus merge versus squash), or cutting a versioned release — the portable git-convention layer for any repo. Covers Conventional Commits, SemVer tags, branch hygiene, force-push safety and gh pr/release mechanics. NOT the land-it decision and pre-ship checklist (that is `ship`), NOT an isolated checkout before coding (that is `worktrees`), NOT CI/CD release automation (that is `deployment`).",
       "tags": [
         "git",
         "version-control",
@@ -2126,7 +2126,7 @@
     },
     {
       "id": "google-workspace",
-      "description": "Use when building server-side automation that reads or writes Gmail, Drive, Calendar, or Sheets against a real Google Workspace account via the official client libraries and a GCP service account — picking the auth mode, scoping OAuth scopes, building the authed client, and debugging 403/429/unauthorized_client errors. Triggers: 'send mail from a service account in a cron', 'unauthorized_client when impersonating a user', 'which Drive scope to upload to a shared drive', 'set up domain-wide delegation client ID', 'getting 403 insufficient permissions from the Sheets API', 'automatizar Gmail con cuenta de servicio sin login del usuario', 'enviar correos desde un script sense login d'usuari'. NOT generic SMTP/marketing/deliverability email (that is email-connector).",
+      "description": "Use when server-side code reads or writes Gmail, Drive, Calendar, or Sheets with a GCP service account and no human in the OAuth loop: picking the auth mode (app-owned vs domain-wide delegation vs keyless), scoping to least privilege, building the authed Node/Python client, staying under per-user quota, and debugging unauthorized_client / 403 / 429. NOT SMTP providers or deliverability (that is `email-connector`), NOT slot-finding and booking UX (that is `calendar-scheduling`).",
       "tags": [
         "google-workspace",
         "gmail-api",
@@ -2235,7 +2235,7 @@
     },
     {
       "id": "htmx",
-      "description": "Use when adding interactivity to a server-rendered app (FastAPI/Jinja, Django, Rails, Laravel, Go templates, Express) without adopting a JS framework, wiring hx-get/post/put/delete plus hx-target plus hx-swap plus hx-trigger, returning HTML fragments instead of JSON, doing out-of-band swaps, or building active search, infinite scroll, inline edit, click-to-load, and polling. Triggers: 'swap a server partial into a div on click', 'return an HTML fragment not JSON', 'render a fragment on HX-Request else the full page', 'update the cart count and drawer from one response', 'live search box without React', 'afegir interactivitat a la meva app Django sense muntar un SPA', 'intercambiar un fragmento HTML del servidor', 'buscador en vivo sin SPA'. NOT a client-state SPA with routing/store (that is react / nextjs).",
+      "description": "Use when adding interactivity to a server-rendered app (FastAPI/Jinja, Django, Rails, Laravel, Go templates, Express) without adopting a JS framework — hx-get/post/put/delete with hx-target, hx-swap and hx-trigger, returning HTML fragments instead of JSON, out-of-band swaps, active search, infinite scroll, inline edit and polling. NOT a client-state SPA with routing and a store (that is `react` or `nextjs`).",
       "tags": [
         "htmx",
         "hypermedia",
@@ -2253,7 +2253,7 @@
     },
     {
       "id": "huggingface",
-      "description": "Use when running open models or working on the Hugging Face platform: calling a model via the Inference Providers router or InferenceClient, downloading/uploading/versioning repos on the Hub with the hf CLI, deploying a dedicated Inference Endpoint with scale-to-zero, hosting a Gradio Space with ZeroGPU, picking an open model by task/license/size, or loading a model locally with transformers. Triggers: 'call an open model through Hugging Face', 'InferenceClient embeddings', 'hf download/upload', 'write a model card', 'router.huggingface.co', 'my hf-inference serverless call 404s on a 70B model', 'scale-to-zero endpoint', 'ZeroGPU Space', 'desplegar un modelo de Hugging Face con escalado a cero'. NOT serving a model locally on your own machine (that is ollama), NOT renting and operating your own GPU box (that is runpod), NOT generating creative images via a hosted API (that is replicate-images), NOT fine-tuning with trl/peft (that is finetuning), NOT building training datasets (that is training-data).",
+      "description": "Use when running open models or working on the Hugging Face platform — the Inference Providers router or InferenceClient, Hub repos via the hf CLI, a dedicated Inference Endpoint with scale-to-zero, a Gradio Space with ZeroGPU, picking an open model by task/license/size, or loading one locally with transformers. NOT serving locally on your own machine (that is `ollama`), NOT renting your own GPU box (that is `runpod`), NOT hosted creative image APIs (that is `replicate-images`), NOT fine-tuning with trl/peft (that is `finetuning`).",
       "tags": [
         "huggingface",
         "inference-providers",
@@ -2335,7 +2335,7 @@
     },
     {
       "id": "inventory",
-      "description": "Use when deciding how much stock to hold and when to reorder it — classifying SKUs, sizing safety stock, setting reorder points and order quantities, and tracking inventory KPIs so a business neither stocks out nor sits on dead stock. Triggers: 'what should my reorder point be', 'how much safety stock', 'run an ABC analysis', 'set up min/max levels', 'should I review weekly or continuously', 'we keep running out of X while sitting on a year of Y', 'too much cash tied up in stock', 'punt de comanda', 'stock de seguretat', 'cuánto stock de seguridad necesito si el proveedor a veces tarda el doble'. NOT raising or negotiating the purchase order itself (that is procurement).",
+      "description": "Use when deciding how much stock to hold and when to reorder it — classifying SKUs, sizing safety stock, setting reorder points and order quantities, and tracking the KPIs that keep a business from either stocking out or sitting on dead stock. NOT raising or negotiating the purchase order itself (that is `procurement`).",
       "tags": [
         "reorder-point",
         "safety-stock",
@@ -2358,7 +2358,7 @@
     },
     {
       "id": "investor-materials",
-      "description": "Use when packaging, organizing, or circulating the documents an investor reads OUTSIDE the meeting — setting up or cleaning a data room, writing the investor one-pager/teaser that earns the first meeting, or drafting the recurring monthly/quarterly investor update — symptoms include unnamed dump-folder files, no follow-on warmth, or needing the attachment a cold email carries. Triggers: 'set up our data room', 'what docs do investors expect before diligence', 'write our investor one-pager / teaser', 'draft this month's investor update', 'our data room is a mess, rename and reorganize the files', 'set up a reusable monthly update format', 'sala de datos para inversores', 'actualización mensual a inversores', 'sala de dades / resum d'una pàgina per a inversors'. NOT the slide narrative (that is pitch-deck), NOT the projection spreadsheet (that is financial-model), NOT the round strategy and investor pipeline (that is fundraising).",
+      "description": "Use when packaging or circulating the documents an investor reads outside the meeting — setting up or cleaning a data room, writing the one-pager or teaser that earns the first meeting, or drafting the recurring monthly investor update. NOT the slide narrative (that is `pitch-deck`), NOT the projection spreadsheet (that is `financial-model`), NOT round strategy and the investor pipeline (that is `fundraising`).",
       "tags": [
         "fundraising",
         "data-room",
@@ -2404,7 +2404,7 @@
     },
     {
       "id": "ip-trademark",
-      "description": "Use when a non-lawyer operator needs to protect a brand or creative work — clearing and choosing a name/logo, deciding whether and where to register a trademark, using ™/® correctly, knowing what copyright they get for free, or checking whether they actually own work they paid a freelancer for. Triggers: 'can I use this name', 'is this trademark taken', 'when can I put the ® on our logo', 'we paid the freelancer so we own it, right?', 'is our AI-generated logo copyrightable', 'register the trademark in the US or the EU', 'someone copied our content, what can we do', '¿puedo registrar esta marca?', '¿de quién es el copyright del logo?'. NOT drafting the IP-assignment clause itself (that is contracts).",
+      "description": "Use when a non-lawyer operator needs to protect a brand or creative work — clearing and choosing a name or logo, deciding whether and where to register a trademark, using the trademark and registered symbols correctly, knowing what copyright is automatic, or checking whether they own work a freelancer was paid for. NOT drafting the IP-assignment clause itself (that is `contracts`).",
       "tags": [
         "intellectual-property",
         "trademark",
@@ -2422,7 +2422,7 @@
     },
     {
       "id": "java",
-      "description": "Use when writing, reviewing, or refactoring modern Java (21+, Java 25 LTS) - records and sealed interfaces as algebraic data types, exhaustive pattern-matching switch over instanceof+cast ladders, virtual-thread (Project Loom) concurrency one-task-per-thread, structured concurrency and ScopedValue replacing ThreadLocal, Stream/Optional/Collector pipelines, compact-constructor validation, parametrized JDBC, and the Maven 3.9 / Gradle 9 build surface against a current JDK. Triggers: \\\"write a Java service\\\", \\\"is this idiomatic Java\\\", \\\"refactor this instanceof ladder\\\", \\\"fetch 500 URLs concurrently\\\", \\\"model this domain with records\\\", .java files, pom.xml, build.gradle, the non-obvious \\\"my ThreadLocal context disappears inside the tasks I submit\\\" (that is ScopedValue), \\\"modela este dominio de pagos con tipos inmutables\\\", \\\"refactoritza aquest switch\\\". NOT Spring framework wiring (that is spring-boot).",
+      "description": "Use when writing, reviewing or refactoring modern Java (21+, 25 LTS) — records and sealed interfaces as algebraic data types, exhaustive pattern-matching switch over instanceof ladders, virtual-thread concurrency, structured concurrency and ScopedValue replacing ThreadLocal, Stream and Optional pipelines, compact-constructor validation, parametrized JDBC, and the Maven/Gradle build surface. NOT Spring framework wiring (that is `spring-boot`).",
       "tags": [
         "java",
         "jvm",
@@ -2462,7 +2462,7 @@
     },
     {
       "id": "kotlin-android",
-      "description": "Use when building or fixing a native Android app in Kotlin + Jetpack Compose with the UDF layered architecture (ViewModel/StateFlow, Hilt, Room, Retrofit, coroutines, type-safe Navigation, Gradle/AGP setup). Triggers: a Compose screen that recomposes every frame or loses state on rotation, wiring ViewModel state into the UI, an offline-first repository, a Hilt DI graph, a Room DAO, build.gradle.kts/version-catalog and AGP/Kotlin floors, 'cómo expongo el estado del ViewModel con StateFlow', 'la pantalla Compose se recompone en cada frame', 'mi app Android pierde el estado al rotar'. NOT shared Android+iOS UI from one Kotlin codebase (that is compose-multiplatform).",
+      "description": "Use when building or fixing a native Android app in Kotlin and Jetpack Compose on the UDF layered architecture — ViewModel/StateFlow, Hilt, Room, Retrofit, coroutines, type-safe Navigation, and the Gradle/AGP surface. NOT shared Android and iOS UI from one Kotlin codebase (that is `compose-multiplatform`).",
       "tags": [
         "kotlin",
         "android",
@@ -2484,7 +2484,7 @@
     },
     {
       "id": "kpi-framework",
-      "description": "Use when a team must decide what to measure before building anything — picking one north-star metric, separating leading input drivers from lagging outputs, adding guardrails so a number can't be gamed, or setting a target that isn't arbitrary. Triggers: 'what should we even be measuring', 'we track 40 KPIs and nothing leads anywhere', 'is signups a leading or lagging indicator', 'set an activation target that won't get gamed', 'pick a north star for the product', 'audit our vanity metrics', 'quins KPIs triem per al producte', 'qué métrica norte elegimos'. NOT building the live dashboard that displays them (that is dashboard), NOT instrumenting the events (that is analytics), NOT the recurring board report (that is reporting).",
+      "description": "Use when a team must decide what to measure before building anything — picking one north-star metric, separating leading input drivers from lagging outputs, adding guardrails so a number cannot be gamed, and setting a target that is not arbitrary. NOT the live dashboard that displays them (that is `dashboard`), NOT instrumenting the events (that is `analytics`), NOT the recurring board report (that is `reporting`).",
       "tags": [
         "north-star-metric",
         "leading-vs-lagging",
@@ -2570,7 +2570,7 @@
     },
     {
       "id": "level-design",
-      "description": "Use when designing a game level, map, arena, or encounter — laying out a blockout/greybox, fixing pacing that drags or spikes, guiding players without hand-holding, placing secrets and rewards, or diagnosing a level that plays as boring, confusing, or where players get lost or stuck. Engine-agnostic craft: the blockout->greybox->playtest->art pipeline, sightlines and landmarks, tension/release rhythm, the introduce->develop->twist->combine encounter progression, readability via light/color/composition, and traversal heatmaps. Triggers: 'design this level', 'my level is boring/confusing', 'players keep getting lost', 'how do I pace this', 'blockout', 'greybox', 'encounter design', 'where do I put the secret'. NOT systemic mechanics or economy tuning (that's game-design), NOT narrative or story beats (that's game-storytelling), and NOT engine-specific level tooling — nav meshes, occlusion, tilemap editors, lightmap baking (that's the godot/unity/unreal skill).",
+      "description": "Use when designing a game level's space — blockout/greybox layout, pacing that drags or spikes, guiding lost players without waypoints, encounter and arena progression, or secret placement. NOT mechanics or economy (that is `game-design`), NOT story beats (that is `game-storytelling`), NOT engine tooling like nav meshes or lightmaps (that is `godot`/`unity`/`unreal`).",
       "tags": [
         "level-design",
         "blockout",
@@ -4466,7 +4466,7 @@
     },
     {
       "id": "spring-boot",
-      "description": "Use when building, reviewing, testing, securing, or configuring a Spring Boot 4 / Spring Framework 7 backend — controllers, services, Spring Data JPA, application.yml, SecurityFilterChain, slice tests. Triggers: 'add a REST endpoint', 'wire up @Service and @Repository', 'my @Transactional isn't rolling back', 'LazyInitializationException after the session closed', 'N+1 select on a lazy collection', '@WebMvcTest + mock the service', 'migrate WebSecurityConfigurerAdapter', 'monta la seguridad con SecurityFilterChain', 'per què surt LazyInitializationException', a file importing org.springframework.boot.*, a pom.xml with spring-boot-starter-web, or an application.yml. NOT plain modern-Java language work like records/streams/virtual threads (that is java); NOT engine-level SQL schema/index/EXPLAIN (that is postgresdb); NOT container/CI mechanics (that is deployment).",
+      "description": "Use when building, reviewing, testing, securing or configuring a Spring Boot 4 / Framework 7 backend — controllers, services, Spring Data JPA, application.yml, SecurityFilterChain, slice tests. NOT plain modern-Java language work like records or virtual threads (that is `java`); NOT engine-level SQL schema/index/EXPLAIN (that is `postgresdb`).",
       "tags": [
         "java",
         "spring",
@@ -4823,7 +4823,7 @@
     },
     {
       "id": "together-fireworks",
-      "description": "Use when calling hosted open-model inference on Together AI or Fireworks AI — pointing the OpenAI SDK at api.together.ai or api.fireworks.ai, picking an open model (Llama, DeepSeek, Qwen, GPT-OSS) and what it costs, or cutting the bill with batch inference. Triggers: 'call DeepSeek/Llama on Together', 'wire the OpenAI SDK to Fireworks', 'why is my model name 404ing', 'which open-source model and how much per million tokens', 'halve my LLM bill with batch', 'move off GPT-4 to a cheaper open-weights endpoint', 'serverless vs dedicated for sustained QPS', '¿qué modelo open source uso y cuánto cuesta?', 'abaratar la factura de inferència'. NOT renting raw GPUs to self-host weights (that is runpod), NOT running a model locally with zero marginal cost (that is ollama).",
+      "description": "Use when calling open-weight LLMs on Together AI or Fireworks AI's OpenAI-compatible endpoints — `base_url` plus namespaced model id, the cheapest model that clears the bar, per-1M-token cost math, serverless vs batch vs dedicated. NOT renting GPUs to self-host weights (that is `runpod`), NOT running a model locally for free (that is `ollama`).",
       "tags": [
         "llm",
         "inference",
@@ -5240,7 +5240,7 @@
     },
     {
       "id": "youtube-api",
-      "description": "Use when connecting a real YouTube channel to code via the Data API v3 (uploads, metadata) and Analytics API v2 (performance) — OAuth, resumable video upload, editing title/description/tags/privacy after publish, pulling views/watch time/averageViewPercentage/retention/traffic sources — and logging that performance into 02-DOCS/wiki/youtube/ as a dated feedback log. Triggers: 'upload a video to my channel via the API and set its tags', 'videos.insert returns 403 quotaExceeded / uploadLimitExceeded', 'my YouTube refresh token keeps dying after about 7 days', 'pull the audienceWatchRatio retention curve for video X', 'fetch this month's traffic sources and write them into the wiki', 'subir vídeos a YouTube por API y guardar las estadísticas del canal', 'treure les estadístiques del canal i guardar-les al wiki'. NOT what-to-publish or how-to-package it (that is youtube-strategy / youtube-packaging).",
+      "description": "Use when wiring code to a real YouTube channel: user OAuth 2.0, resumable videos.insert uploads, editing metadata after publish, pulling views/watch time/retention/traffic from the Analytics API v2 into a dated 02-DOCS/wiki/youtube/ feedback log. NOT what to publish or how to title and thumbnail it (that is youtube-strategy / youtube-packaging).",
       "tags": [
         "youtube",
         "youtube-data-api",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ericrisco/rsc",
-  "version": "0.1.57",
+  "version": "0.1.59",
   "description": "Eric Risco's agent-skills catalog as a granular, self-recommending CLI installer.",
   "type": "module",
   "bin": {

package/skills/gamedev-physics/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: gamedev-physics
-description: "Use when working with a game engine's physics — rigid bodies, colliders, collision layers/masks, character controllers, joints, forces vs impulses, raycasts/shapecasts, or when physics is unstable. Triggers: \"my character falls through the floor\", \"bullet tunnels through walls at high speed\", \"rigidbody jitters / vibrates / explodes\", \"objects that should collide pass through each other\", \"which collision layer and mask do I set\", \"kinematic vs dynamic body\", \"move_and_slide / CharacterBody\", \"AddForce vs impulse vs setting velocity\", \"physics in FixedUpdate or _physics_process\", \"slope and step detection\", \"trigger / Area overlap not firing\", Godot RigidBody/StaticBody/CharacterBody/Area, Unity Rigidbody/Collider/CharacterController, Unreal Chaos/collision presets. NOT rendering, materials, or visual jitter from shaders (use gamedev-shaders); NOT AI navigation, pathfinding, or navmesh (use gamedev-pathing)."
+description: "Use when working with a game engine's physics — rigid bodies, colliders, collision layers and masks, character controllers, joints, forces versus impulses, raycasts and shapecasts, or when a simulation is unstable (tunnelling, jitter, missed overlaps). Covers the Godot, Unity and Unreal equivalents. NOT rendering or shader-driven visual jitter (that is `gamedev-shaders`), NOT navigation, pathfinding or navmesh (that is `gamedev-pathing`)."
 tags: [physics, collision, rigidbody, character-controller, colliders]
 recommends: [godot, unity, unreal, gamedev-pathing]
 profiles: [full]

package/skills/git-workflow/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: git-workflow
-description: "Use when naming or scoping a branch, writing or fixing a commit message, untangling history (rebase vs merge vs squash), or cutting a versioned release — the portable git-convention layer that works on any repo. Triggers: 'name this branch', 'is this commit message conventional?', 'rebase or merge before the PR?', 'squash these wip commits into one', 'my git log is a mess', 'tag a release', 'write release notes', 'what version should this release be?', 'clean up history before review', 'limpia el historial antes del PR', '¿qué versión le toca a esta release?', 'deja los commits en formato convencional'. Covers Conventional Commits 1.0.0, SemVer tags, branch hygiene, force-push safety, and gh pr/release mechanics. NOT the I'm-done land-it decision and pre-ship checklist (that is ship), NOT setting up an isolated checkout before coding (that is worktrees), NOT CI/CD release automation in GitHub Actions (that is deployment)."
+description: "Use when naming or scoping a branch, writing or fixing a commit message, untangling history (rebase versus merge versus squash), or cutting a versioned release — the portable git-convention layer for any repo. Covers Conventional Commits, SemVer tags, branch hygiene, force-push safety and gh pr/release mechanics. NOT the land-it decision and pre-ship checklist (that is `ship`), NOT an isolated checkout before coding (that is `worktrees`), NOT CI/CD release automation (that is `deployment`)."
 tags: [git, version-control, conventional-commits, semver, pull-request]
 recommends: [ship, worktrees, deployment, github-actions]
 origin: risco

package/skills/google-workspace/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: google-workspace
-description: "Use when building server-side automation that reads or writes Gmail, Drive, Calendar, or Sheets against a real Google Workspace account via the official client libraries and a GCP service account — picking the auth mode, scoping OAuth scopes, building the authed client, and debugging 403/429/unauthorized_client errors. Triggers: 'send mail from a service account in a cron', 'unauthorized_client when impersonating a user', 'which Drive scope to upload to a shared drive', 'set up domain-wide delegation client ID', 'getting 403 insufficient permissions from the Sheets API', 'automatizar Gmail con cuenta de servicio sin login del usuario', 'enviar correos desde un script sense login d'usuari'. NOT generic SMTP/marketing/deliverability email (that is email-connector)."
+description: "Use when server-side code reads or writes Gmail, Drive, Calendar, or Sheets with a GCP service account and no human in the OAuth loop: picking the auth mode (app-owned vs domain-wide delegation vs keyless), scoping to least privilege, building the authed Node/Python client, staying under per-user quota, and debugging unauthorized_client / 403 / 429. NOT SMTP providers or deliverability (that is `email-connector`), NOT slot-finding and booking UX (that is `calendar-scheduling`)."
 tags: [google-workspace, gmail-api, drive-api, calendar-api, sheets-api, service-account, domain-wide-delegation, oauth-scopes]
 recommends: [email-connector, calendar-scheduling, spreadsheet-ops, document-processing, automation-flows, secure-coding, webhooks]
 origin: risco
@@ -9,52 +9,22 @@ origin: risco
 # Google Workspace — auth + calling Gmail/Drive/Calendar/Sheets
 
 This skill owns one layer: **authenticating to and calling the four Google
-Workspace REST APIs from server-side code.** You pick the auth mode, scope the
-OAuth scopes to least privilege, build the authed client in Node or Python, and
-call Gmail / Drive / Calendar / Sheets with quota-safe patterns. It turns "I
-have a GCP project and a Workspace domain" into code that sends mail, moves
-files, books events, and reads/writes spreadsheets without a human in the OAuth
-loop.
-
-It does NOT own email-as-a-product, scheduling-as-a-product, or
-spreadsheet-as-data. See the boundaries below before you start.
-
-Operating posture:
-
-- **No human in the loop.** Everything here is service-account / machine auth.
-  If a real user must click "Allow", that is interactive OAuth — out of scope.
-- **Least scope, keyless first.** Default to the narrowest scope and to
-  Application Default Credentials / Workload Identity Federation over a
-  downloaded JSON key. A leaked key is the single most common Workspace
-  credential compromise.
-- **Quota is a real constraint, not a footnote.** The per-user limits are tight
-  (6k units/min Gmail, 60 req/min Sheets). Build backoff in from line one.
-
-## When to use / When NOT to use
-
-**Use when:** a cron, webhook handler, or agent tool reads/writes Gmail, Drive,
-Calendar, or Sheets without an interactive login; you must decide between
-app-owned resources and impersonating each Workspace user; you hit
-`403 insufficient permissions`, `403 rateLimitExceeded`, `429`, or
-`unauthorized_client` and need the scope/delegation/quota fix; you are wiring
-`googleapis` (Node) or `google-api-python-client` + `google-auth` (Python);
-you are migrating off downloaded JSON keys toward keyless auth.
-
-**Do NOT use for:**
-
-- **Generic transactional/marketing email, SMTP, providers, deliverability,
-  SPF/DKIM** → `email-connector` and `email-deliverability`. This skill covers
-  Gmail-the-API inside a Workspace mailbox, not provider choice or inbox
-  placement.
-- **Scheduling logic, availability, booking-link UX, timezone-as-a-feature** →
-  `calendar-scheduling`. This skill covers the raw Calendar event CRUD it sits
-  on top of.
-- **Spreadsheet data modeling, formulas, pivots, transforms as the deliverable**
-  → `spreadsheet-ops`. This skill covers the Sheets API read/write transport.
-- **Doc/PDF parsing, extraction, OCR** → `document-processing`. Drive here is
-  storage transport (upload/download/move/permissions), not content extraction.
-- **Multi-step orchestration across connectors** → `automation-flows`. **Notion**
-  → `notion-connector`. **Generic REST wrapping** → `api-connector-builder`.
+Workspace REST APIs from server-side code.** Everything here is service-account
+/ machine auth — if a real user must click "Allow", that is interactive OAuth and
+out of scope.
+
+Where the neighbouring layers live:
+
+| Not this skill | Goes to | This skill's slice |
+|---|---|---|
+| SMTP/provider choice, transactional/marketing sends | `email-connector` | Gmail-the-API inside a Workspace mailbox |
+| SPF/DKIM, inbox placement | `email-deliverability` | — |
+| Availability search, booking-link UX, timezone-as-a-feature | `calendar-scheduling` | Raw Calendar event CRUD underneath |
+| Sheet data modeling, formulas, pivots | `spreadsheet-ops` | Sheets API read/write transport |
+| Doc/PDF parsing, extraction, OCR | `document-processing` | Drive as storage transport (upload/download/move/permissions) |
+| Chaining several connectors into one flow | `automation-flows` | The individual Google calls |
+| Notion as the backend / generic REST wrapping | `notion-connector`, `api-connector-builder` | — |
+| Receiving Gmail/Drive push notifications | `webhooks` | — |
 
 ## Pick your auth mode
 
@@ -72,7 +42,9 @@ large blast radius. Use it only when you genuinely must act as the user.
 
 ## Setup checklist
 
-Do these in order. The full click-path is in `references/auth-setup.md`.
+Do these in order. `references/auth-setup.md` has the full Cloud + Admin
+click-path, the scope catalog, DWD authorization, keyless WIF/ADC, and a longer
+troubleshooting matrix.
 
 1. **Enable the APIs** you will call in the Cloud console (Gmail, Drive,
    Calendar, Sheets) for the project. A disabled API returns `403` regardless of
@@ -242,8 +214,9 @@ def with_backoff(call, max_retries=6, max_backoff=64):
 - **Never commit the SA key JSON.** It is a long-lived bearer credential — a
   committed `service_account.json` is game over. Add `*.json` SA patterns to
   `.gitignore`; the `verify.sh` here flags tracked keys.
-- **Prefer keyless.** On GCP/CI use ADC or Workload Identity Federation so there
-  is no file to leak. If you must use a key, store it in a secret manager
+- **Prefer keyless.** A leaked key is the single most common Workspace credential
+  compromise. On GCP/CI use ADC or Workload Identity Federation so there is no
+  file to leak. If you must use a key, store it in a secret manager
   (env-injected, not a file beside the code) and rotate it.
 - **Least scope.** A leaked `drive.file` key sees app files; a leaked full
   `drive` key sees everything. The scope IS the blast radius.
@@ -268,20 +241,6 @@ def with_backoff(call, max_retries=6, max_backoff=64):
 | Reading whole resources without `fields` | Bigger payloads, higher quota cost, slower | Request only the fields you use (`fields: 'id'`) |
 | Hardcoding the private key inline in source | Can't rotate, leaks via logs/screenshots/history | Inject from env/secret manager; `\n`-unescape at load |
 | Pasting raw text into Gmail `raw` | API needs base64url RFC 822, not plain text → 400 | Build a MIME message, `base64url`-encode it |
-| Setting `subject` but skipping the Admin DWD step | `unauthorized_client` — the SA was never allowed to impersonate | Authorize client ID + exact scopes in Manage DWD first |
-
-## See also
-
-- `../secure-coding/SKILL.md` — secret handling, key rotation, and the security
-  pass before this connector ships.
-
-Recommended companions (siblings; create/link when present): `email-connector`
-for SMTP/provider/deliverability email, `calendar-scheduling` for slot-finding
-and booking UX, `spreadsheet-ops` for sheet data modeling and formulas,
-`document-processing` for parsing files you pull from Drive, `automation-flows`
-for chaining this across multiple connectors, and `webhooks` for receiving
-Gmail/Drive push notifications.
 
-Deep dives: `references/auth-setup.md` (full Cloud + Admin walkthrough, scope
-catalog, DWD authorization, keyless WIF/ADC, troubleshooting matrix) and
-`references/api-recipes.md` (extended Node + Python recipes).
+Before this connector ships, run the secret-handling and key-rotation pass in
+`../secure-coding/SKILL.md`.

package/skills/htmx/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: htmx
-description: "Use when adding interactivity to a server-rendered app (FastAPI/Jinja, Django, Rails, Laravel, Go templates, Express) without adopting a JS framework, wiring hx-get/post/put/delete plus hx-target plus hx-swap plus hx-trigger, returning HTML fragments instead of JSON, doing out-of-band swaps, or building active search, infinite scroll, inline edit, click-to-load, and polling. Triggers: 'swap a server partial into a div on click', 'return an HTML fragment not JSON', 'render a fragment on HX-Request else the full page', 'update the cart count and drawer from one response', 'live search box without React', 'afegir interactivitat a la meva app Django sense muntar un SPA', 'intercambiar un fragmento HTML del servidor', 'buscador en vivo sin SPA'. NOT a client-state SPA with routing/store (that is react / nextjs)."
+description: "Use when adding interactivity to a server-rendered app (FastAPI/Jinja, Django, Rails, Laravel, Go templates, Express) without adopting a JS framework — hx-get/post/put/delete with hx-target, hx-swap and hx-trigger, returning HTML fragments instead of JSON, out-of-band swaps, active search, infinite scroll, inline edit and polling. NOT a client-state SPA with routing and a store (that is `react` or `nextjs`)."
 tags: [htmx, hypermedia, frontend, server-rendered, html]
 recommends: [fastapi, django, secure-coding, accessibility]
 origin: risco

package/skills/huggingface/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: huggingface
-description: "Use when running open models or working on the Hugging Face platform: calling a model via the Inference Providers router or InferenceClient, downloading/uploading/versioning repos on the Hub with the hf CLI, deploying a dedicated Inference Endpoint with scale-to-zero, hosting a Gradio Space with ZeroGPU, picking an open model by task/license/size, or loading a model locally with transformers. Triggers: 'call an open model through Hugging Face', 'InferenceClient embeddings', 'hf download/upload', 'write a model card', 'router.huggingface.co', 'my hf-inference serverless call 404s on a 70B model', 'scale-to-zero endpoint', 'ZeroGPU Space', 'desplegar un modelo de Hugging Face con escalado a cero'. NOT serving a model locally on your own machine (that is ollama), NOT renting and operating your own GPU box (that is runpod), NOT generating creative images via a hosted API (that is replicate-images), NOT fine-tuning with trl/peft (that is finetuning), NOT building training datasets (that is training-data)."
+description: "Use when running open models or working on the Hugging Face platform — the Inference Providers router or InferenceClient, Hub repos via the hf CLI, a dedicated Inference Endpoint with scale-to-zero, a Gradio Space with ZeroGPU, picking an open model by task/license/size, or loading one locally with transformers. NOT serving locally on your own machine (that is `ollama`), NOT renting your own GPU box (that is `runpod`), NOT hosted creative image APIs (that is `replicate-images`), NOT fine-tuning with trl/peft (that is `finetuning`)."
 tags: [huggingface, inference-providers, transformers, model-hub, inference-endpoints, spaces, ai-infra]
 recommends: [ollama, runpod, modal, replicate, together-fireworks, fal, rag, embeddings-search, prompt-engineering, llm-pipeline, ai-media]
 origin: risco

package/skills/inventory/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: inventory
-description: "Use when deciding how much stock to hold and when to reorder it — classifying SKUs, sizing safety stock, setting reorder points and order quantities, and tracking inventory KPIs so a business neither stocks out nor sits on dead stock. Triggers: 'what should my reorder point be', 'how much safety stock', 'run an ABC analysis', 'set up min/max levels', 'should I review weekly or continuously', 'we keep running out of X while sitting on a year of Y', 'too much cash tied up in stock', 'punt de comanda', 'stock de seguretat', 'cuánto stock de seguridad necesito si el proveedor a veces tarda el doble'. NOT raising or negotiating the purchase order itself (that is procurement)."
+description: "Use when deciding how much stock to hold and when to reorder it — classifying SKUs, sizing safety stock, setting reorder points and order quantities, and tracking the KPIs that keep a business from either stocking out or sitting on dead stock. NOT raising or negotiating the purchase order itself (that is `procurement`)."
 tags: [reorder-point, safety-stock, eoq, abc-xyz, replenishment, inventory-kpis, ddmrp, min-max]
 recommends: [procurement, logistics-ops, forecasting, dashboard, reporting, spreadsheet-ops]
 origin: risco

package/skills/investor-materials/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: investor-materials
-description: "Use when packaging, organizing, or circulating the documents an investor reads OUTSIDE the meeting — setting up or cleaning a data room, writing the investor one-pager/teaser that earns the first meeting, or drafting the recurring monthly/quarterly investor update — symptoms include unnamed dump-folder files, no follow-on warmth, or needing the attachment a cold email carries. Triggers: 'set up our data room', 'what docs do investors expect before diligence', 'write our investor one-pager / teaser', 'draft this month's investor update', 'our data room is a mess, rename and reorganize the files', 'set up a reusable monthly update format', 'sala de datos para inversores', 'actualización mensual a inversores', 'sala de dades / resum d'una pàgina per a inversors'. NOT the slide narrative (that is pitch-deck), NOT the projection spreadsheet (that is financial-model), NOT the round strategy and investor pipeline (that is fundraising)."
+description: "Use when packaging or circulating the documents an investor reads outside the meeting — setting up or cleaning a data room, writing the one-pager or teaser that earns the first meeting, or drafting the recurring monthly investor update. NOT the slide narrative (that is `pitch-deck`), NOT the projection spreadsheet (that is `financial-model`), NOT round strategy and the investor pipeline (that is `fundraising`)."
 tags: [fundraising, data-room, investor-update, one-pager, investor-relations, due-diligence]
 recommends: [pitch-deck, financial-model, fundraising, cold-outreach, unit-economics, grants]
 origin: risco

package/skills/ip-trademark/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: ip-trademark
-description: "Use when a non-lawyer operator needs to protect a brand or creative work — clearing and choosing a name/logo, deciding whether and where to register a trademark, using ™/® correctly, knowing what copyright they get for free, or checking whether they actually own work they paid a freelancer for. Triggers: 'can I use this name', 'is this trademark taken', 'when can I put the ® on our logo', 'we paid the freelancer so we own it, right?', 'is our AI-generated logo copyrightable', 'register the trademark in the US or the EU', 'someone copied our content, what can we do', '¿puedo registrar esta marca?', '¿de quién es el copyright del logo?'. NOT drafting the IP-assignment clause itself (that is contracts)."
+description: "Use when a non-lawyer operator needs to protect a brand or creative work — clearing and choosing a name or logo, deciding whether and where to register a trademark, using the trademark and registered symbols correctly, knowing what copyright is automatic, or checking whether they own work a freelancer was paid for. NOT drafting the IP-assignment clause itself (that is `contracts`)."
 tags: [intellectual-property, trademark, copyright, licensing, legal-compliance]
 recommends: [contracts, brand-identity, compliance, terms-conditions]
 origin: risco

package/skills/java/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: java
-description: "Use when writing, reviewing, or refactoring modern Java (21+, Java 25 LTS) - records and sealed interfaces as algebraic data types, exhaustive pattern-matching switch over instanceof+cast ladders, virtual-thread (Project Loom) concurrency one-task-per-thread, structured concurrency and ScopedValue replacing ThreadLocal, Stream/Optional/Collector pipelines, compact-constructor validation, parametrized JDBC, and the Maven 3.9 / Gradle 9 build surface against a current JDK. Triggers: \"write a Java service\", \"is this idiomatic Java\", \"refactor this instanceof ladder\", \"fetch 500 URLs concurrently\", \"model this domain with records\", .java files, pom.xml, build.gradle, the non-obvious \"my ThreadLocal context disappears inside the tasks I submit\" (that is ScopedValue), \"modela este dominio de pagos con tipos inmutables\", \"refactoritza aquest switch\". NOT Spring framework wiring (that is spring-boot)."
+description: "Use when writing, reviewing or refactoring modern Java (21+, 25 LTS) — records and sealed interfaces as algebraic data types, exhaustive pattern-matching switch over instanceof ladders, virtual-thread concurrency, structured concurrency and ScopedValue replacing ThreadLocal, Stream and Optional pipelines, compact-constructor validation, parametrized JDBC, and the Maven/Gradle build surface. NOT Spring framework wiring (that is `spring-boot`)."
 tags: [java, jvm, records, virtual-threads, sealed-types]
 recommends: [spring-boot, secure-coding, deployment]
 origin: risco

package/skills/kotlin-android/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: kotlin-android
-description: "Use when building or fixing a native Android app in Kotlin + Jetpack Compose with the UDF layered architecture (ViewModel/StateFlow, Hilt, Room, Retrofit, coroutines, type-safe Navigation, Gradle/AGP setup). Triggers: a Compose screen that recomposes every frame or loses state on rotation, wiring ViewModel state into the UI, an offline-first repository, a Hilt DI graph, a Room DAO, build.gradle.kts/version-catalog and AGP/Kotlin floors, 'cómo expongo el estado del ViewModel con StateFlow', 'la pantalla Compose se recompone en cada frame', 'mi app Android pierde el estado al rotar'. NOT shared Android+iOS UI from one Kotlin codebase (that is compose-multiplatform)."
+description: "Use when building or fixing a native Android app in Kotlin and Jetpack Compose on the UDF layered architecture — ViewModel/StateFlow, Hilt, Room, Retrofit, coroutines, type-safe Navigation, and the Gradle/AGP surface. NOT shared Android and iOS UI from one Kotlin codebase (that is `compose-multiplatform`)."
 tags: [kotlin, android, jetpack-compose, hilt, room, coroutines, mvvm, clean-architecture]
 recommends: [compose-multiplatform, spring-boot, java, testing-web, github-actions]
 origin: risco

package/skills/kpi-framework/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: kpi-framework
-description: "Use when a team must decide what to measure before building anything — picking one north-star metric, separating leading input drivers from lagging outputs, adding guardrails so a number can't be gamed, or setting a target that isn't arbitrary. Triggers: 'what should we even be measuring', 'we track 40 KPIs and nothing leads anywhere', 'is signups a leading or lagging indicator', 'set an activation target that won't get gamed', 'pick a north star for the product', 'audit our vanity metrics', 'quins KPIs triem per al producte', 'qué métrica norte elegimos'. NOT building the live dashboard that displays them (that is dashboard), NOT instrumenting the events (that is analytics), NOT the recurring board report (that is reporting)."
+description: "Use when a team must decide what to measure before building anything — picking one north-star metric, separating leading input drivers from lagging outputs, adding guardrails so a number cannot be gamed, and setting a target that is not arbitrary. NOT the live dashboard that displays them (that is `dashboard`), NOT instrumenting the events (that is `analytics`), NOT the recurring board report (that is `reporting`)."
 tags: [north-star-metric, leading-vs-lagging, input-metrics, guardrail-metrics, target-setting, vanity-metrics, kpi-tree]
 recommends: [analytics, dashboard, reporting, ab-testing, forecasting, business-intelligence, unit-economics, project-ops]
 origin: risco

package/skills/level-design/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: level-design
-description: "Use when designing a game level, map, arena, or encounter — laying out a blockout/greybox, fixing pacing that drags or spikes, guiding players without hand-holding, placing secrets and rewards, or diagnosing a level that plays as boring, confusing, or where players get lost or stuck. Engine-agnostic craft: the blockout->greybox->playtest->art pipeline, sightlines and landmarks, tension/release rhythm, the introduce->develop->twist->combine encounter progression, readability via light/color/composition, and traversal heatmaps. Triggers: 'design this level', 'my level is boring/confusing', 'players keep getting lost', 'how do I pace this', 'blockout', 'greybox', 'encounter design', 'where do I put the secret'. NOT systemic mechanics or economy tuning (that's game-design), NOT narrative or story beats (that's game-storytelling), and NOT engine-specific level tooling — nav meshes, occlusion, tilemap editors, lightmap baking (that's the godot/unity/unreal skill)."
+description: "Use when designing a game level's space — blockout/greybox layout, pacing that drags or spikes, guiding lost players without waypoints, encounter and arena progression, or secret placement. NOT mechanics or economy (that is `game-design`), NOT story beats (that is `game-storytelling`), NOT engine tooling like nav meshes or lightmaps (that is `godot`/`unity`/`unreal`)."
 tags: [level-design, blockout, pacing, encounter, playtest]
 recommends: [game-design, godot, unity, unreal]
 profiles: [full]
@@ -11,29 +11,12 @@ origin: risco
 
 *Shape the space, the rhythm, and the encounters so the player always knows where to go, never gets bored, and feels smart for exploring. Prove it in grey boxes; add art last.*
 
-This skill owns the **craft of physical space and its play**: how a level is laid out, how it reads, how its intensity rises and falls, how encounters teach, and where reward hides. It is **engine-agnostic** — every technique here is validated in a blockout, then handed to an engine skill for the actual tooling (nav meshes, occlusion, lightmaps, tilemaps). It does not design the mechanics the level exercises (that's the systemic layer) or write the story it tells.
-
-## When to use / When NOT to use
-
-**Use when:** blocking out a new level/map/arena; a level playtests as boring, confusing, or too hard/easy; players get lost or stuck; you need to pace a level, space encounters, or add breathers; you're guiding players without arrows/waypoints; placing secrets, rewards, or shortcuts; teaching a mechanic through the space itself.
-
-**Do NOT use for:**
-
-- **Systemic / mechanic design** — the verbs, rules, economy, and numbers the player brings *into* the level (jump height as a rule, weapon balance, loot tables, progression systems). That's `game-design`. This skill *exercises* those verbs in space; it doesn't invent or tune them.
-- **Narrative, quests, dialogue, environmental story beats** — what the space *says*. That's `game-storytelling`. Level design places the beat; storytelling writes it.
-- **Engine-specific level tooling** — nav-mesh baking, occlusion culling, terrain/tilemap/ProBuilder editors, lightmap/GI bakes, streaming volumes, collision setup. Defer to `godot` / `unity` / `unreal`. This skill decides *what* the space must do; the engine skill implements *how*.
-
-## The craft laws (non-negotiable)
-
-1. **Art last.** Never model or texture a space you haven't proven fun in blockout. Art-first means reworking expensive assets when the layout inevitably changes.
-2. **Metrics before geometry.** Lock the player's dimensions (height, jump, reach, cover) first; build everything as multiples of them. → `references/blockout-to-art.md`
-3. **The player always knows where to go, never how it ends.** Guide the critical path; leave exploration to earn its own reward. Lostness is a readability bug, not player error.
-4. **Watch, don't tell.** A level is only as good as it plays for someone you didn't coach. Every claim ("this is obvious", "the fight is fun") is a hypothesis until a fresh player validates it.
-5. **Rhythm, not a flat line.** Intensity must rise and fall. Sustained peak = fatigue; sustained calm = boredom. Design the graph, not just the rooms.
-6. **Teach through space, not text.** Introduce a threat where it's safe to learn it, before it can kill.
+This skill owns the **craft of physical space and its play**: how a level is laid out, how it reads, how its intensity rises and falls, how encounters teach, and where reward hides. It is **engine-agnostic** — every technique here is validated in a blockout, then handed to an engine skill for the actual tooling.
 
 ## The pipeline: blockout -> greybox -> playtest -> art (never art-first)
 
+**Lock the player's metrics first** — height, jump, reach, cover, door/corridor widths — and build all geometry as multiples of them. Guessing widths breaks traversal after the space is full of dependent geometry, which is why this comes before the first box. → `references/blockout-to-art.md`
+
 | Stage | You build | You answer | Gate to next |
 |---|---|---|---|
 | **Blockout** | Primitive geometry only (boxes/planes at true metrics). No materials, no props. | Does the space flow? Are timings/distances right? Can I find my way? | Layout & traversal feel right. |
@@ -41,7 +24,7 @@ This skill owns the **craft of physical space and its play**: how a level is lai
 | **Playtest** | Nothing — you watch fresh players. | Where do they hesitate, get lost, die, skip? | Fixes are cheap because it's still grey. |
 | **Art pass** | Meshes, materials, VFX, final lighting, audio — *serving* the proven layout. | Does art reinforce the guidance the greybox already established? | Ship. |
 
-Iterate blockout↔playtest many times before art. Changing a grey box is minutes; changing a finished art set-piece is days. Full stage detail, the metrics block, and the art-pass handoff checklist → `references/blockout-to-art.md`.
+Iterate blockout↔playtest many times before art: changing a grey box is minutes, changing a finished art set-piece is days — so never model or texture a space you have not already proven fun. Full stage detail, the metrics block, and the art-pass handoff checklist → `references/blockout-to-art.md`.
 
 ## Spatial composition — leading the eye
 
@@ -49,13 +32,13 @@ Iterate blockout↔playtest many times before art. Changing a grey box is minute
 - **Landmarks (the "weenie").** One large, distinct, distant silhouette per area that the player orients toward (tower, spire, mountain) — Disney's term for the visual magnet that pulls you forward. Self-locating beats a minimap.
 - **Lead the eye** with converging lines (rails, beams), framing (foreground arches), contrast (a bright end to a dark corridor), and motion. The eye goes to the brightest, highest-contrast, most-different thing — put that on the path you want taken.
 - **Silhouette readability.** Enemies, interactables, and hazards must read by shape alone at a glance. Two things sharing a silhouette is an unintended trap.
-- **Golden path vs exploration.** The **critical path** is the always-legible guaranteed route to the objective; **exploration** is optional branches and loops off it. Prefer loops that return the player forward (avoid dead-end backtracking); breadcrumb side routes with a visible reward.
+- **Golden path vs exploration.** The **critical path** is the always-legible guaranteed route to the objective; **exploration** is optional branches and loops off it. The player must always know where to go and never how it ends. Prefer loops that return the player forward (avoid dead-end backtracking); breadcrumb side routes with a visible reward.
 
 Framing, contrast, and layout topologies (loops, hubs, gates) → `references/guidance-and-readability.md`.
 
 ## Pacing & rhythm — tension and release
 
-Design the **intensity graph** for the whole level, not room by room. A good level is a sawtooth trending upward: each peak (combat, platforming gauntlet, chase) followed by a valley — a **safe room / breather** with no threat, low stimulus, often a save/restock.
+Design the **intensity graph** for the whole level, not room by room. Intensity must rise and fall — sustained peak is fatigue, sustained calm is boredom. A good level is a sawtooth trending upward: each peak (combat, platforming gauntlet, chase) followed by a valley — a **safe room / breather** with no threat, low stimulus, often a save/restock.
 
 - **Space encounters in time and distance, and *vary* both** — three identical-length fights back to back feel like one long slog.
 - **Breathers earn the next peak.** The calm between (Halo's cadence is often described as "thirty seconds of fun" on repeat) is what makes the fun read as fun. Use it to let adrenaline drop, reward observation, and telegraph the next escalation.
@@ -66,7 +49,7 @@ Intensity-graph template, breather patterns, and difficulty-curve worked example
 
 ## Encounter design — introduce, develop, twist, combine
 
-The four-beat progression teaches a mechanic/threat through space (the pattern behind Portal, Half-Life 2, and Mario level craft):
+Teach through space, not text: the four-beat progression (the pattern behind Portal, Half-Life 2, and Mario level craft) introduces a threat where it is safe to learn, before it can kill.
 
 1. **Introduce** — meet the new element somewhere it *can't* hurt you. A single turret across a safe gap; one platform of the new hazard. Learn it risk-free.
 2. **Develop** — use it for real, low stakes. The turret now guards a corridor you must cross.
@@ -84,7 +67,7 @@ Encounter template, arena patterns, and a full introduce→develop→twist→com
 
 ## Guidance & readability — direct without hand-holding
 
-Guide with the environment so you never need a floating arrow:
+Guide with the environment so you never need a floating arrow. When a player is lost, that is a readability bug in the level, not player error:
 
 - **Light leads.** Players move toward light (the moth effect) and higher value-contrast. Light the path, objective, and exit; keep dead-ends dim. Placeholder lighting is a greybox *design* tool, not a final-art afterthought.
 - **Reserve one accent color for "you can interact / go here"** (Mirror's Edge runner red, Dishonored's usable glint) and **never** use it decoratively. Consistency is the whole point; break it once and you've lied to the player.
@@ -96,7 +79,7 @@ Full catalog — lighting/color/composition, the affordance language, the "criti
 
 ## Metrics & playtesting — where players get lost and stuck
 
-You cannot see your own level fresh. **Observe, don't coach:**
+You cannot see your own level fresh, so every claim ("this is obvious", "the fight is fun") is a hypothesis until a fresh player validates it. **Observe, don't coach:**
 
 - **Watch a first-timer play, silent.** Note every hesitation (readability gap), wrong turn (navigation gap), repeated death (telegraph/difficulty gap), and skipped content (reward-placement gap). Do **not** answer "where do I go?" — that question *is* the finding.
 - **Traversal telemetry** turns anecdote into pattern: **position heatmaps** (cold zones players never enter = wasted level), **death heatmaps** (clusters = unfair/unreadable threats), **path traces** (golden path or lost?), **dwell time** at forks (long dwell = unclear guidance), and **look/aim heatmaps** (did they even see the landmark?).
@@ -114,41 +97,26 @@ Playtest protocol, question scripts, and turning heatmaps into fixes → `refere
 
 Reward taxonomy, secret-signposting, and risk/reward tuning → `references/guidance-and-readability.md`.
 
-## Anti-patterns / rationalizations -> STOP
+## Anti-patterns
 
-| Rationalization | Reality / Fix |
+| Anti-pattern | Do instead |
 |---|---|
-| "Let's make it look good first, then tune the layout." | Art-first burns days reworking assets when the layout changes. Blockout, playtest, *then* art. |
-| "It's obvious where to go." | Obvious to *you*, the author. Fresh players get lost. Watch one before you believe it. |
-| "I'll just add a waypoint arrow / big text prompt." | That's a patch over a readability failure. Fix it with light, framing, and a landmark first. |
-| "The whole level is intense — it's exciting!" | Sustained peak = fatigue and it all flattens into noise. Add breathers so the peaks read. |
-| "Backtracking reuses the space for free." | Repeated dead-end backtracking reads as padding. Use loops that return the player forward. |
-| "Players will figure the new mechanic out." | Not while it's killing them. Introduce it where it's safe, then develop/twist/combine. |
-| "Yellow paint everywhere so they see the ledges." | Only if yellow means *exactly* climbable and appears nowhere else. Inconsistent affordances lie. |
-| "The secret's hidden well — no one will find it." | A secret with no breadcrumb is just frustration. Show the thread; reward the curious eye. |
-| "The gap/cover/door width feels about right." | Guessing metrics breaks traversal later. Set the metrics block first; build to multiples. |
-
-## Quick reference
-
-| Lever | Default | Where |
-|---|---|---|
-| Build order | blockout → greybox → playtest → art (art last) | `references/blockout-to-art.md` |
-| Metrics block | lock player height/jump/reach/cover first; build to multiples | `references/blockout-to-art.md` |
-| Navigation | one dominant landmark per area; legible critical path + breadcrumbed loops | `references/guidance-and-readability.md` |
-| Pacing | sawtooth: peak → breather (safe room) → higher peak | `references/pacing-and-encounters.md` |
-| Encounter teaching | introduce → develop → twist → combine | `references/pacing-and-encounters.md` |
-| Arena shape | sightline length matched to threat range; flanks + verticality | `references/pacing-and-encounters.md` |
-| Guidance | light leads; one reserved interact color; consistent affordances | `references/guidance-and-readability.md` |
-| Playtest | watch silent; log hesitation/lost/death/skip; read heatmaps | `references/guidance-and-readability.md` |
-| Secrets / risk | breadcrumb them; best optional reward behind biggest optional risk | `references/guidance-and-readability.md` |
+| Making it look good first, then tuning the layout. | Art-first burns days reworking assets when the layout changes. Blockout, playtest, *then* art. |
+| Trusting that it's "obvious where to go". | Obvious to *you*, the author. Fresh players get lost. Watch one before you believe it. |
+| Patching confusion with a waypoint arrow or big text prompt. | That's a patch over a readability failure. Fix it with light, framing, and a landmark first. |
+| Keeping the whole level intense because intensity is exciting. | Sustained peak = fatigue and it all flattens into noise. Add breathers so the peaks read. |
+| Reusing the space by sending the player back the way they came. | Repeated dead-end backtracking reads as padding. Use loops that return the player forward. |
+| Dropping a new mechanic in and expecting players to figure it out. | Not while it's killing them. Introduce it where it's safe, then develop/twist/combine. |
+| Yellow paint everywhere so they see the ledges. | Only if yellow means *exactly* climbable and appears nowhere else. Inconsistent affordances lie. |
+| Hiding a secret so well nobody finds it. | A secret with no breadcrumb is just frustration. Show the thread; reward the curious eye. |
+| Eyeballing gap, cover, and door widths because they feel about right. | Guessing metrics breaks traversal later. Set the metrics block first; build to multiples. |
 
 ## Related skills
 
-- **`game-design`** — the systemic layer: mechanics, verbs, economy, progression, difficulty *systems*. Level design exercises those verbs in space; if the request is about the rules themselves, route there.
-- **`game-storytelling`** — narrative, quests, dialogue, and the meaning of environmental beats. Level design places the beat; storytelling authors it.
-- **`godot` / `unity` / `unreal`** — the engine tooling that *implements* a proven layout: nav meshes, occlusion, terrain/tilemap editors, lightmap/GI bakes, streaming, collision. Hand off here after the blockout plays well.
-- **`harness`** — the `02-DOCS` Karpathy-wiki this skill records level conventions into.
-- **References:** `references/blockout-to-art.md` (pipeline, metrics block, art handoff, playtesting the blockout); `references/pacing-and-encounters.md` (intensity graph, encounter template, arena patterns, difficulty curve); `references/guidance-and-readability.md` (light/color/composition, affordances, playtest protocol, telemetry, reward & secrets).
+- `game-design` — the systemic layer: mechanics, verbs, economy, progression, difficulty *systems*. Level design exercises those verbs in space; if the request is about the rules themselves, route there.
+- `game-storytelling` — narrative, quests, dialogue, and the meaning of environmental beats. Level design places the beat; storytelling authors it.
+- `godot` / `unity` / `unreal` — the engine tooling that *implements* a proven layout: nav meshes, occlusion, terrain/tilemap editors, lightmap/GI bakes, streaming, collision. Hand off here after the blockout plays well.
+- `harness` — the `02-DOCS` Karpathy-wiki this skill records level conventions into.
 
 ## Checklist
 

package/skills/spring-boot/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: spring-boot
-description: "Use when building, reviewing, testing, securing, or configuring a Spring Boot 4 / Spring Framework 7 backend — controllers, services, Spring Data JPA, application.yml, SecurityFilterChain, slice tests. Triggers: 'add a REST endpoint', 'wire up @Service and @Repository', 'my @Transactional isn't rolling back', 'LazyInitializationException after the session closed', 'N+1 select on a lazy collection', '@WebMvcTest + mock the service', 'migrate WebSecurityConfigurerAdapter', 'monta la seguridad con SecurityFilterChain', 'per què surt LazyInitializationException', a file importing org.springframework.boot.*, a pom.xml with spring-boot-starter-web, or an application.yml. NOT plain modern-Java language work like records/streams/virtual threads (that is java); NOT engine-level SQL schema/index/EXPLAIN (that is postgresdb); NOT container/CI mechanics (that is deployment)."
+description: "Use when building, reviewing, testing, securing or configuring a Spring Boot 4 / Framework 7 backend — controllers, services, Spring Data JPA, application.yml, SecurityFilterChain, slice tests. NOT plain modern-Java language work like records or virtual threads (that is `java`); NOT engine-level SQL schema/index/EXPLAIN (that is `postgresdb`)."
 tags: [java, spring, jpa, security, backend]
 recommends: [java, postgresdb, secure-coding, deployment]
 origin: risco
@@ -23,47 +23,18 @@ If you are typing `WebSecurityConfigurerAdapter`, `@MockBean`, field `@Autowired
 `authorizeRequests`, or `javax.persistence` — **stop**. Those are the previous generation.
 The modern idioms below replace every one of them.
 
-## When to use
-
-- Writing or reviewing any `@RestController`, `@Service`, `@Repository`, `@Component`,
-  `@Configuration`, Spring Data JPA `@Entity`, or repository interface.
-- JPA persistence: entity mapping, `JpaRepository`, derived queries, `@Query`,
-  `@Transactional` boundaries, fetch strategy / N+1, pagination.
-- Spring Security: `SecurityFilterChain`, method security, JWT resource server, OAuth2
-  client, password encoding, CORS.
-- Configuration & profiles: `application.yml`, `@ConfigurationProperties`, `@Profile`,
-  externalized secrets, `spring.config.import`.
-- Testing: `@SpringBootTest` vs slices (`@WebMvcTest`, `@DataJpaTest`), `@MockitoBean`,
-  `MockMvc`, Testcontainers + `@ServiceConnection`.
-
-## When NOT to use
+## Boundaries
 
 - Plain Java language work (records, sealed types, virtual threads, streams, pattern
-  matching) with no Spring -> **`../java/SKILL.md`**.
-- Async Python FastAPI -> **`../fastapi/SKILL.md`**. NestJS/Node -> **`../nestjs/SKILL.md`**. Django -> `django`.
+  matching) with no Spring -> [`../java/SKILL.md`](../java/SKILL.md).
+- Async Python FastAPI -> [`../fastapi/SKILL.md`](../fastapi/SKILL.md). NestJS/Node ->
+  [`../nestjs/SKILL.md`](../nestjs/SKILL.md). Django -> [`../django/SKILL.md`](../django/SKILL.md).
 - Engine-level SQL: schema/index design, `EXPLAIN`, partitioning, zero-downtime DDL ->
-  **`../postgresdb/SKILL.md`** (this skill drives the JPA layer above it).
-- Language-agnostic injection/authz/secret theory -> **`../secure-coding/SKILL.md`**.
-- Dockerfile/Compose/CI/CD mechanics -> **`../deployment/SKILL.md`** (keep only a build note here).
-
-## Decision rules
-
-1. **Constructor injection only — final fields, no `@Autowired` on fields.** A class whose
-   collaborators are constructor args is testable with `new` and fails fast on a missing bean.
-2. **Controller stays thin: parse, validate, delegate, map.** Any branch with business
-   meaning belongs in the service, where it is transactional and unit-testable without MVC.
-3. **`@Transactional` lives on service methods, never on a controller or repository.** The
-   transaction must wrap the unit of work, not the HTTP request or a single query.
-4. **Expose DTO records in and out — never the `@Entity`.** Returning an entity leaks columns
-   and triggers lazy loads inside the JSON serializer (the classic `LazyInitializationException`).
-5. **Typed `@ConfigurationProperties` record over scattered `@Value`.** One validated binding
-   beats string keys sprinkled across the codebase and gives you a fail-fast startup.
-6. **Security is a `SecurityFilterChain` bean with the lambda DSL** — `authorizeHttpRequests`
-   + `requestMatchers`. `WebSecurityConfigurerAdapter`, `authorizeRequests`, `antMatchers` are gone.
-7. **Reach for the narrowest test slice first.** `@WebMvcTest` for a controller,
-   `@DataJpaTest` for a repository; `@SpringBootTest` only when you genuinely need the full context.
-8. **Validate at the edge with `@Valid` + Bean Validation (`jakarta.validation`).** Reject
-   bad input before it reaches the service so business code assumes valid data.
+  [`../postgresdb/SKILL.md`](../postgresdb/SKILL.md) (this skill drives the JPA layer above it).
+- Language-agnostic injection/authz/secret theory ->
+  [`../secure-coding/SKILL.md`](../secure-coding/SKILL.md).
+- Dockerfile/Compose/CI/CD mechanics -> [`../deployment/SKILL.md`](../deployment/SKILL.md)
+  (keep only a build note here).
 
 ## Project layout
 
@@ -84,9 +55,12 @@ com.acme.shop
 
 ## Controllers
 
-`@RestController` + DTO records, `@Valid` on the body, `ResponseEntity` for 201/`Location`,
-a `@RestControllerAdvice` for one error envelope. Boot 4 adds first-class versioning via a
-`version` attribute on the mapping — one controller serves many versions, no path duplication.
+`@RestController` + DTO records, `@Valid` on the body (Bean Validation, `jakarta.validation`)
+so business code can assume valid data, `ResponseEntity` for 201/`Location`, a
+`@RestControllerAdvice` for one error envelope. The controller parses, validates, delegates
+and maps — any branch with business meaning belongs in the service, where it is transactional
+and unit-testable without MVC. Boot 4 adds first-class versioning via a `version` attribute
+on the mapping — one controller serves many versions, no path duplication.
 
 ```java
 @RestController
@@ -120,7 +94,7 @@ class ApiExceptionHandler {
 record ApiError(String code, String message, List<String> details) {}
 ```
 
-**Bad -> Good** — never return the entity:
+**Bad -> Good** — never return the entity; it leaks columns and lazy-loads in the serializer:
 
 ```java
 // Bad: leaks columns; lazy fields blow up in the serializer after the tx closes.
@@ -132,7 +106,9 @@ record ApiError(String code, String message, List<String> details) {}
 ## Service + transactions
 
 Constructor-injected, `final` fields, `@Transactional` on the write path, `readOnly = true`
-on queries (lets Hibernate skip dirty checking).
+on queries (lets Hibernate skip dirty checking). `@Transactional` belongs on service methods,
+never on a controller or repository: the transaction must wrap the unit of work, not the HTTP
+request or a single query.
 
 ```java
 @Service
@@ -233,11 +209,13 @@ record AppProperties(Duration inviteTtl, int maxOrdersPerDay) {}   // typed, val
 ```
 
 **Bad -> Good** — scattered `@Value("${app.max-orders-per-day}")` strings vs one injected
-`AppProperties` record. Typed binding fails fast on a missing/mistyped key instead of NPE-ing later.
+`AppProperties` record. One typed binding beats string keys sprinkled across the codebase and
+fails fast on a missing/mistyped key instead of NPE-ing later.
 
 ## Security
 
-A single `SecurityFilterChain` bean, stateless for token APIs, JWT via the resource server.
+A single `SecurityFilterChain` bean with the lambda DSL, stateless for token APIs, JWT via the
+resource server.
 
 ```java
 @Configuration
@@ -264,11 +242,12 @@ Order `requestMatchers` from most specific to least — the first match wins, so
 `permitAll` placed early opens routes you meant to lock. Full JWT/OAuth2 client, method
 security, CORS, and CSRF posture (token vs cookie apps) live in
 [`references/security.md`](references/security.md). For the language-agnostic authz/secret
-principles behind these rules, see `../secure-coding/SKILL.md`.
+principles behind these rules, see [`../secure-coding/SKILL.md`](../secure-coding/SKILL.md).
 
 ## Testing
 
-Pick the narrowest slice that exercises what you changed:
+Pick the narrowest slice that exercises what you changed — `@SpringBootTest` only when you
+genuinely need the full context:
 
 | Slice | Loads | Use for | Collaborators |
 |---|---|---|---|
@@ -324,14 +303,17 @@ interface BillingClient {
 `@Retryable` and `@ConcurrencyLimit` are core in Framework 7 — no extra Spring Retry
 dependency for the basics.
 
-## Anti-patterns / rationalizations -> STOP
+## Anti-patterns
 
-| You are about to... | Why it's wrong | Do instead |
+| Anti-pattern | Why it's wrong | Do instead |
 |---|---|---|
 | Extend `WebSecurityConfigurerAdapter` | Removed in Security 6/7 | `SecurityFilterChain` bean + lambda DSL |
 | `@Autowired` on a field | Untestable, hides missing beans till runtime | constructor injection, `final` fields |
 | `@Transactional` on a `@RestController` | Tx must wrap the unit of work, not the request | put it on the service method |
+| Business branching in the controller | Not transactional, needs MVC to test | move the decision into the `@Service` |
 | Return the `@Entity` from a controller | Leaks columns, lazy-loads in serializer (LIE) | map to a DTO record inside the tx |
+| Request body reaching the service unvalidated | Business code can no longer assume valid data | `@Valid` + `jakarta.validation` at the edge |
+| Scattered `@Value("${...}")` config keys | String keys, no validation, fails late | one typed `@ConfigurationProperties` record |
 | Use `@MockBean` / `@SpyBean` | Replaced in Boot 4 | `@MockitoBean` / `@MockitoSpyBean` |
 | `import javax.persistence` / `javax.validation` | Jakarta EE 11 baseline | `jakarta.*` |
 | `authorizeRequests` / `antMatchers` | Gone in Security 6/7 | `authorizeHttpRequests` + `requestMatchers` |
@@ -341,6 +323,8 @@ dependency for the basics.
 | `catch (Exception e)` and echo `e.getMessage()` | Leaks internals, swallows bugs | `@RestControllerAdvice` + typed error envelope |
 | Serialize a lazy collection after the tx closes | `LazyInitializationException` / N+1 | fetch join or `@EntityGraph`, map in-tx |
 
+`scripts/verify.sh` greps a project for the legacy idioms above (read-only, best effort).
+
 ## Quick reference
 
 | Task | Idiom |
@@ -364,12 +348,3 @@ If the repo has a `02-DOCS/` wiki, record stack decisions (Boot version, securit
 test strategy, migration tool) in `02-DOCS/wiki/stack/spring-boot.md` and link it from the
 `CLAUDE.md` Knowledge map. This is recorded, not gated — if there is no `02-DOCS/`, skip
 silently; you may suggest the project harness if the user wants persistent docs.
-
-## See also
-
-- `../java/SKILL.md` — the language underneath (records, virtual threads, streams).
-- `../postgresdb/SKILL.md` — the engine under JPA (schema, indexes, `EXPLAIN`).
-- `../secure-coding/SKILL.md` — the authz/injection/secret principles behind the security rules.
-- `../deployment/SKILL.md` — packaging the jar, container, CI.
-- [`references/jpa.md`](references/jpa.md) · [`references/security.md`](references/security.md) · [`references/testing.md`](references/testing.md)
-- `scripts/verify.sh` — best-effort static reviewer for legacy Spring idioms.

package/skills/spring-boot/evals/cases.yaml

@@ -4,7 +4,7 @@ should_trigger:
   - prompt: "Add a REST endpoint to create an order in our Spring Boot service."
     why: "Core controller/service work — the central job of the skill."
   - prompt: "My @Transactional method isn't rolling back when it throws, why?"
-    why: "Non-obvious proxy self-invocation + checked-exception-no-rollback rule; a defining Spring trap."
+    why: "Non-obvious proxy self-invocation + checked-exception-no-rollback trap; documented in the service/transactions section."
   - prompt: "I get LazyInitializationException when the JSON serializer reads the response."
     why: "Classic JPA fetch/session-boundary symptom; the fix is map-to-DTO-in-tx, a core rule here."
   - prompt: "Migra esta config de seguridad, usa WebSecurityConfigurerAdapter y está deprecada."
@@ -12,7 +12,7 @@ should_trigger:
   - prompt: "Set up a @WebMvcTest for the controller and mock the service."
     why: "Slice testing + @MockitoBean — non-obvious that @MockBean is the wrong (removed) idiom."
   - prompt: "Configura @ConfigurationProperties con perfiles para esta app."
-    why: "Catalan/Spanish; typed config + profiles is a named decision rule."
+    why: "Catalan/Spanish; typed @ConfigurationProperties + profiles is a documented config surface."
   - prompt: "We have N+1 selects on a lazy collection — how do I fetch-join it?"
     why: "JPA fetch strategy / @EntityGraph, a documented depth area."
 

package/skills/together-fireworks/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: together-fireworks
-description: "Use when calling hosted open-model inference on Together AI or Fireworks AI — pointing the OpenAI SDK at api.together.ai or api.fireworks.ai, picking an open model (Llama, DeepSeek, Qwen, GPT-OSS) and what it costs, or cutting the bill with batch inference. Triggers: 'call DeepSeek/Llama on Together', 'wire the OpenAI SDK to Fireworks', 'why is my model name 404ing', 'which open-source model and how much per million tokens', 'halve my LLM bill with batch', 'move off GPT-4 to a cheaper open-weights endpoint', 'serverless vs dedicated for sustained QPS', '¿qué modelo open source uso y cuánto cuesta?', 'abaratar la factura de inferència'. NOT renting raw GPUs to self-host weights (that is runpod), NOT running a model locally with zero marginal cost (that is ollama)."
+description: "Use when calling open-weight LLMs on Together AI or Fireworks AI's OpenAI-compatible endpoints — `base_url` plus namespaced model id, the cheapest model that clears the bar, per-1M-token cost math, serverless vs batch vs dedicated. NOT renting GPUs to self-host weights (that is `runpod`), NOT running a model locally for free (that is `ollama`)."
 tags: [llm, inference, together-ai, fireworks-ai, openai-compatible, open-models, batch, cost]
 recommends: [runpod, modal, ollama, huggingface, fal, cost-tracking, llm-pipeline, prompt-engineering, embeddings-search]
 origin: risco
@@ -107,7 +107,7 @@ Fuller catalog and embedding/fine-tuning numbers: `references/models-and-pricing
 
 Decision: **real-time → serverless. Big offline job (eval, synthetic data, bulk classify) → batch. Sustained heavy traffic with an SLA → dedicated.**
 
-> **Gotcha — Together batch is NOT the OpenAI Batch endpoint.** Together's OpenAI-compat layer does **not** expose `/v1/batches`. Use Together's **native Batch API**: upload a JSONL file, default **24h** window, up to **50,000 requests/file**, up to **50% off**, separate rate-limit pool. Pointing the OpenAI Batch client at Together fails. Fireworks instead exposes Batch as a serving *path* through the one API (Serverless 2.0: Standard / Priority / Batch), batch = 50% of serverless. See `references/batch-and-tuning.md`.
+> **Gotcha — Together batch is NOT the OpenAI Batch endpoint.** Together's OpenAI-compat layer does **not** expose `/v1/batches`. Use Together's **native Batch API**: upload a JSONL file, default **24h** window, up to **50,000 requests/file**, up to **50% off**, separate rate-limit pool. Pointing the OpenAI Batch client at Together fails. Fireworks instead exposes Batch as a serving *path* through the one API (Serverless 2.0: Standard / Priority / Batch), batch = 50% of serverless. JSONL shape, the upload/poll/download flow, limits, and dedicated-deployment notes: `references/batch-and-tuning.md`.
 
 Two more Fireworks multipliers worth knowing:
 - **Cached input tokens default to 50%** of input price (text/vision models) — repeated prefixes get cheaper automatically.
@@ -173,9 +173,4 @@ Keep the id mapping in config, not in `if provider == ...` branches scattered th
 | Treating these like free/local | They bill per token; ollama is the zero-marginal-cost path | If cost must be zero and weights run on your box → `../ollama/SKILL.md` |
 | Renting GPUs to "save money" then idling them | A serverless token endpoint has no idle cost | Self-host only at sustained scale → `../runpod/SKILL.md` |
 
-## References
-
-- `references/models-and-pricing.md` — fuller per-provider model + pricing tables, embeddings, fine-tuning costs, with a re-check note.
-- `references/batch-and-tuning.md` — Together native Batch API JSONL shape + upload/poll/download flow and limits; Fireworks batch path; dedicated deployment notes.
-
 Validate any inference snippet/config with `scripts/verify.sh <file-or-dir>` — a static, no-network lint for the right base URLs, namespaced model ids, and env-var keys.

package/skills/youtube-api/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: youtube-api
-description: "Use when connecting a real YouTube channel to code via the Data API v3 (uploads, metadata) and Analytics API v2 (performance) — OAuth, resumable video upload, editing title/description/tags/privacy after publish, pulling views/watch time/averageViewPercentage/retention/traffic sources — and logging that performance into 02-DOCS/wiki/youtube/ as a dated feedback log. Triggers: 'upload a video to my channel via the API and set its tags', 'videos.insert returns 403 quotaExceeded / uploadLimitExceeded', 'my YouTube refresh token keeps dying after about 7 days', 'pull the audienceWatchRatio retention curve for video X', 'fetch this month's traffic sources and write them into the wiki', 'subir vídeos a YouTube por API y guardar las estadísticas del canal', 'treure les estadístiques del canal i guardar-les al wiki'. NOT what-to-publish or how-to-package it (that is youtube-strategy / youtube-packaging)."
+description: "Use when wiring code to a real YouTube channel: user OAuth 2.0, resumable videos.insert uploads, editing metadata after publish, pulling views/watch time/retention/traffic from the Analytics API v2 into a dated 02-DOCS/wiki/youtube/ feedback log. NOT what to publish or how to title and thumbnail it (that is youtube-strategy / youtube-packaging)."
 tags: [youtube, youtube-data-api, youtube-analytics-api, oauth2, resumable-upload, video-metadata, audience-retention, channel-feedback-log]
 recommends: [social-publisher, api-connector-builder, automation-flows, knowledge-ops]
 origin: risco
@@ -17,31 +17,20 @@ YouTube has **two separate APIs** and you will touch both:
 
 Auth is **user OAuth 2.0, not a service account.** A human owns the channel; you act on their behalf with a refresh token. A service account cannot own a YouTube channel — if you reach for one, stop. (Service-account Google auth for Gmail/Drive/Sheets is `google-workspace`, a different model.)
 
-## When to use / When NOT
-
-Use when:
-
-- Wiring a script or agent to upload to a channel (`videos.insert`), set metadata, schedule a publish, or set a custom thumbnail.
-- Editing an existing video's title/description/tags/privacy after publish (`videos.update`).
-- Pulling channel or per-video stats: views, `estimatedMinutesWatched`, `averageViewPercentage`, the audience-retention curve, the traffic-source breakdown.
-- Building the recurring "fetch performance → write to `02-DOCS/wiki/youtube/`" loop that turns API responses into a channel feedback log.
-- Debugging `403 quotaExceeded`, `uploadLimitExceeded` (429), `401 invalid_credentials`, scope errors, or a refresh token that dies after a week.
-
-Do NOT use when (route to the sibling that owns it):
+Route elsewhere when the job is not transport:
 
 | You actually want | Go to |
 | --- | --- |
-| What videos to make / niche / cadence / growth plan | `youtube-strategy` *(catalog id)* |
-| Video ideas, hooks, a topic backlog | `youtube-ideation` *(catalog id)* |
-| Title + thumbnail packaging, CTR copy, A/B framing | `youtube-packaging` *(catalog id)* |
+| What videos to make / niche / cadence / growth plan | `../youtube-strategy/SKILL.md` |
+| Video ideas, hooks, a topic backlog | `../youtube-ideation/SKILL.md` |
+| Title + thumbnail packaging, CTR copy, A/B framing | `../youtube-packaging/SKILL.md` |
 | The thumbnail image itself | `../youtube-thumbnails/SKILL.md` |
 | Render/produce the actual video file in code | `../remotion-video/SKILL.md` |
 | Post one asset across many networks at once | `../social-publisher/SKILL.md` |
-| Wrap an arbitrary REST provider with OAuth + retries | `api-connector-builder` *(catalog id)* |
-| Chain upload → Notion row → Slack across tools | `automation-flows` *(catalog id)* |
-| Service-account auth to Gmail/Drive/Sheets | `google-workspace` *(catalog id)* |
-
-One line: **this skill authenticates, calls, and ingests the two YouTube APIs into the wiki. What to publish and how to package it belong to the youtube-strategy / youtube-ideation / youtube-packaging siblings.**
+| Wrap an arbitrary REST provider with OAuth + retries | `../api-connector-builder/SKILL.md` |
+| Chain upload → Notion row → Slack across tools | `../automation-flows/SKILL.md` |
+| Service-account auth to Gmail/Drive/Sheets | `../google-workspace/SKILL.md` |
+| Generic wiki structure and conventions | `../knowledge-ops/SKILL.md` |
 
 ## 1. One-time setup (do this before any code)
 
@@ -151,7 +140,7 @@ video_id = resp["id"]
 data.thumbnails().set(videoId=video_id, media_body=MediaFileUpload("ep14.jpg")).execute()
 ```
 
-Two separate limits, not one — and uploads no longer come out of the 10k unit pool. As of the official quota docs (Last updated 2026-06-01 UTC, `https://developers.google.com/youtube/v3/getting-started`), a project's default allocation is *"100 search.list calls, 100 videos.insert calls, and 10,000 units per day combined for all other endpoints."* So `videos.insert` has its **own dedicated cap of ~100 uploads/day**, charged against that allocation rather than spending ~1,600 units of the 10k pool like the older model. That ~100/day call cap is exactly what trips `uploadLimitExceeded` (429) while your 10k unit pool still looks untouched. Throttle the upload **count** against the 100/day allocation, not just the unit spend — space automated uploads out and back off on 429.
+Throttle the upload **count**, not the unit spend: `videos.insert` has its own cap of ~100 uploads/day, so `uploadLimitExceeded` (429) hits while the 10k unit pool still looks untouched. Space automated uploads out and back off on 429 — figures and citation in §7.
 
 ## 4. Edit metadata after publish
 
@@ -254,7 +243,7 @@ Rule: **append, never overwrite.** The feedback log *is* the value — overwriti
 | `*.list` read | 1–5 units (from the 10k pool) |
 | Analytics `reports.query` | (separate Analytics quota) |
 
-Per the official docs (Last updated 2026-06-01 UTC, `https://developers.google.com/youtube/v3/getting-started`; per-method costs at `https://developers.google.com/youtube/v3/determine_quota_cost`), a project's default allocation is **100 `search.list` calls + 100 `videos.insert` calls + 10,000 units/day combined for all other endpoints**. Uploads and search each draw on their *own* daily call cap; everything else (writes, reads) spends the shared 10k-unit pool. All quotas reset at midnight Pacific. This is a change from the older single-pool model where `videos.insert` cost ~1,600 units — confirm the live figure on the quota-cost page before relying on it, since Google notes the allocation "is subject to change."
+Per the official docs (Last updated 2026-06-01 UTC, `https://developers.google.com/youtube/v3/getting-started`; per-method costs at `https://developers.google.com/youtube/v3/determine_quota_cost`), a project's default allocation is *"100 search.list calls, 100 videos.insert calls, and 10,000 units per day combined for all other endpoints."* All quotas reset at midnight Pacific. This is a change from the older single-pool model where `videos.insert` cost ~1,600 units — confirm the live figure on the quota-cost page before relying on it, since Google notes the allocation "is subject to change."
 
 On `403 quotaExceeded` / `rateLimitExceeded` or `429`: **exponential backoff with jitter**, then stop for the day on a hard quota cap — retrying a daily-quota 403 in a tight loop just burns the next day too.
 
@@ -281,11 +270,3 @@ Error → cause map:
 | Treat the 10k unit pool as the upload budget | Uploads use a separate ~100/day call cap, so `uploadLimitExceeded` 429 hits with the pool untouched | Throttle upload count against the ~100/day cap |
 | Overwrite yesterday's wiki snapshot | Destroys the trend the siblings read | Append a new dated entry every pull |
 | Leave the app in "Testing" | Token silently dies in 7 days | Publish to "In production" |
-
-## Cross-references
-
-- `../youtube-thumbnails/SKILL.md` — the thumbnail image this skill only *sets*.
-- `../social-publisher/SKILL.md` — when the asset goes to many networks, not just YouTube.
-- `../remotion-video/SKILL.md` — produce the video file this skill uploads.
-- `youtube-strategy`, `youtube-ideation`, `youtube-packaging` *(catalog ids)* — what the numbers *mean* and what to do next.
-- `api-connector-builder`, `automation-flows`, `knowledge-ops` *(catalog ids)* — generic connector wrapping, cross-tool chaining, and wiki conventions.