@ericrisco/rsc 0.1.52 → 0.1.53

package/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.1.52",
+  "version": "0.1.53",
   "counts": {
     "skills": 258
   },
@@ -1950,7 +1950,7 @@
     },
     {
       "id": "gamedev-shaders",
-      "description": "Use when writing shaders, materials, VFX, or post-processing for a game engine, or asking \\\"how do I make this effect\\\" — covers the vertex→fragment pipeline, UVs / normals / coordinate spaces, and per-engine authoring in Godot 4.x (shader_type spatial/canvas_item/particles, source_color, hint_screen_texture, ShaderMaterial), Unity 6 (Shader Graph vs HLSL, URP/HDRP, ShaderLab), and Unreal 5.x (Material graph, material domains, Custom HLSL node). Includes recipes for dissolve, rim/outline, toon/cel, water/flow, force field, hologram; full-screen post-process; and shader performance (overdraw, texture-sample cost, branching, mobile). Triggers: \\\"write a dissolve shader\\\", \\\"rim light\\\", \\\"toon shading\\\", \\\"screen-space effect\\\", \\\"my shader is slow on mobile\\\", \\\"cómo hago un shader de agua\\\". NOT gameplay or engine-API code (→ godot / unity / unreal) and NOT physics simulation, collision, or rigid bodies (→ gamedev-physics).",
+      "description": "Use when authoring or debugging a shader, material, VFX, or full-screen post-process in a game engine — Godot 4.x `.gdshader`, Unity 6 URP/HDRP, Unreal 5.x Materials, effect recipes, shader performance. NOT gameplay or engine-API code (that is `godot`/`unity`/`unreal`), NOT physics (`gamedev-physics`), NOT build variant stripping (`gamedev-shipping`).",
       "tags": [
         "shaders",
         "vfx",
@@ -1995,7 +1995,7 @@
     },
     {
       "id": "gcp-essentials",
-      "description": "Use when running a small product on the core of Google Cloud with the gcloud CLI: creating a project, deploying a container to Cloud Run, standing up a Cloud Storage bucket, a managed Cloud SQL Postgres/MySQL, and wiring them together with least-privilege IAM. Triggers: 'deploy to Cloud Run', 'gcloud run deploy', 'set up a GCP project', 'crear bucket en GCP', 'desplegar a Cloud Run', 'service account sin claves JSON', 'why is my Cloud Run running as the default service account', 'connect Cloud Run to Cloud SQL', 'turn off the bucket public access'. NOT AWS (that is aws-essentials).",
+      "description": "Use when running a small product on core Google Cloud via the gcloud CLI: a project, Cloud Run deploys, a locked-down Cloud Storage bucket, managed Cloud SQL, and least-privilege IAM wiring them together. NOT AWS (that is `aws-essentials`), NOT the CI pipeline that ships the image (that is `deployment`), NOT Postgres schema/query tuning (that is `postgresdb`).",
       "tags": [
         "gcp",
         "cloud-run",
@@ -2192,7 +2192,7 @@
     },
     {
       "id": "hetzner",
-      "description": "Use when provisioning or hardening a Hetzner Cloud VPS to host real apps: picking a plan/location (CX/CPX/CAX/CCX), bringing a box up reproducibly with the hcloud CLI + cloud-init, locking down SSH, and wiring the Hetzner Cloud Firewall before handing off a Docker/Coolify-ready host. Triggers: 'set up a Hetzner server', 'provision a Hetzner VPS', 'harden SSH on my box', 'which Hetzner plan for a small API', 'configure the Hetzner Cloud Firewall', the non-obvious 'my ipv6-only box is cheaper but docker pull can't reach the registry', and the Spanish/Catalan 'monta un servidor en Hetzner', 'configura el firewall de Hetzner'. NOT deploying apps through Coolify (that is coolify).",
+      "description": "Use when provisioning or hardening a Hetzner Cloud VPS: picking the plan/location (CX/CPX/CAX/CCX), bringing it up reproducibly with hcloud + cloud-init, locking down SSH, and wiring the Cloud Firewall to hand off a Docker-ready host. NOT app deploys on Coolify (that is `coolify`), NOT Dockerfiles (that is `docker`), NOT another provider (that is `digitalocean`).",
       "tags": [
         "hetzner",
         "vps",
@@ -2439,7 +2439,7 @@
     },
     {
       "id": "knowledge-ops",
-      "description": "Use when an already-running 02-DOCS/ wiki needs day-to-day gardening — too many half-finished articles, a 600-line page that covers three unrelated topics, a note with no obvious home, orphan pages nothing links to, stale answers and superseded articles piling up, or two articles that contradict each other. This is the judgment layer over harness's automation: decide what is worth capturing (default: nothing), where it goes, how to title/split/merge it, build the See Also web, and prune to _archive (never delete). Triggers: 'limpia mi wiki', 'organiza mis notas', 'esto dónde va en la wiki', 'ordena la base de conocimiento', 'split this bloated article', 'where should this note live', 'scores.json says these three are orphans — fix the cross-links', 'prune the stale and superseded stuff'. NOT building, bootstrapping or sweeping the wiki engine (that is harness).",
+      "description": "Use when an already-running 02-DOCS/ wiki needs gardening judgment — what is worth capturing (default: nothing), where a loose note belongs, whether to split a bloated article or merge near-duplicates, how to link orphans back in, and what retires to _archive (never delete). NOT building or sweeping the wiki engine itself (that is `harness`).",
       "tags": [
         "knowledge-ops",
         "wiki",
@@ -2827,7 +2827,7 @@
     },
     {
       "id": "medium-publishing",
-      "description": "Use when getting a finished article onto Medium correctly — choosing profile vs publication, cross-posting from your own site without an SEO duplicate-content hit, the import tool, the 5-tag limit, and Medium's pseudo-Markdown formatting gotchas. Triggers: 'cross-post to Medium', 'republish on Medium with a canonical link', 'submit my draft to a Medium publication', 'why are my code blocks broken on Medium', 'can I still automate Medium via the API', 'the Medium import tool failed with a 403', 'importar mi artículo a Medium sin penalización SEO', 'publicar a Medium amb enllaç canònic'. NOT drafting, structuring, or headlining the article itself (that is medium-writing).",
+      "description": "Use when a finished article has to land on Medium correctly — profile vs publication, cross-posting under a canonical link so your own site keeps the SEO credit, import-tool failures, the 5-tag cap, pseudo-Markdown gotchas. NOT writing or headlining the piece (that is `medium-writing`), NOT cadence or earnings (that is `medium-strategy`).",
       "tags": [
         "medium",
         "publishing",
@@ -2992,7 +2992,7 @@
     },
     {
       "id": "n8n",
-      "description": "Use when operating a live n8n instance programmatically — driving its public REST API (`{host}/api/v1`, `X-N8N-API-KEY`) or the n8n-mcp server to create, validate, test, activate/deactivate, list, update, or delete workflows and read executions, on self-host or `*.app.n8n.cloud`. Triggers: 'deploy this workflow to my n8n over the API', 'push my workflow JSON to n8n with curl', 'I set active:true in the create call but it stays inactive', 'connect n8n-mcp / n8n_create_workflow to Claude', 'validate and autofix my n8n workflow', 'run an n8n workflow by id from a script', 'delete a workflow via the API', 'automatiza n8n por API', 'desplega el workflow a n8n.cloud'. NOT designing the flow's trigger-step-error logic or hand-building the importable workflow JSON (that is automation-flows), NOT operating Make / Zapier / Power Automate (their own skills), NOT a typed API client with auth+pagination+retry (api-connector-builder), NOT the inbound webhook receiver in your own app (webhooks).",
+      "description": "Use when operating a live n8n instance programmatically — its REST API (`{host}/api/v1`, `X-N8N-API-KEY`) or the n8n-mcp server — to create, validate, test, activate, update, delete workflows and read executions on self-host or n8n.cloud. NOT designing the flow or its importable JSON (that is `automation-flows`), NOT another platform (`make`, `zapier`).",
       "tags": [
         "n8n",
         "automation",
@@ -3177,7 +3177,7 @@
     },
     {
       "id": "notion-connector",
-      "description": "Use when wiring an app, cron job, or service to Notion as an ops backend over the official HTTP API — pushing rows into a Notion database, mirroring a database into your app, syncing both ways without duplicates, building or reading page block content, or fixing an integration that broke after the 2025-09-03 data-source split. Triggers: 'store our tasks in a Notion database from code', 'use Notion as a CRM/content calendar', 'sync our CRM into Notion nightly without duplicates', 'why does POST /v1/databases/:id/query return 404 now', 'integration broke after a teammate added a second data source', 'guardar registros en una base de datos de Notion desde código', 'desar files a una base de dades de Notion'. NOT a generic call-any-REST-API integration (that is api-connector-builder), NOT receiving/verifying inbound Notion webhook events (that is webhooks).",
+      "description": "Use when wiring server code or a cron job to Notion as an ops backend over its HTTP API: pushing or mirroring database rows, two-way sync without duplicates, page blocks, or an integration broken by the 2025-09-03 data-source split. NOT generic REST wiring (that is `api-connector-builder`), NOT inbound Notion webhook events (that is `webhooks`).",
       "tags": [
         "notion",
         "ops-backend",
@@ -3406,7 +3406,7 @@
     },
     {
       "id": "planetscale",
-      "description": "Use when operating PlanetScale serverless MySQL (Vitess) — setting up a database/branch and wiring the pscale CLI, shipping a schema change through branches and deploy requests, debugging a stuck/queued deploy or a cutover that won't finish, designing tables without foreign keys, or picking the serverless HTTP driver for an edge runtime. Triggers: 'schema change without downtime on PlanetScale', 'my migration is stuck in the deploy queue', 'the cutover hung', 'can I still revert 40 minutes after deploy', 'the 30-minute revert window', 'PlanetScale won't let me add a foreign key', 'relationMode prisma', 'MySQL connection times out on Vercel Edge', 'cambio de esquema sin downtime', 'no me deja usar foreign keys'. NOT raw MySQL query tuning, EXPLAIN, or index choice (that is postgresdb's MySQL-engine analogue / the mysql sibling), and NOT generic expand-contract migration theory (that is db-migrations).",
+      "description": "Use when operating PlanetScale (Vitess serverless MySQL) — branches and the `pscale` CLI, schema changes through deploy requests (Online DDL cutover, ~30-min revert window), tables without foreign keys, or the edge HTTP driver. NOT MySQL engine work like EXPLAIN or index choice (that is `mysql`), NOT generic migration theory (that is `db-migrations`).",
       "tags": [
         "planetscale",
         "vitess",

package/package.json

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

package/skills/gamedev-shaders/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: gamedev-shaders
-description: "Use when writing shaders, materials, VFX, or post-processing for a game engine, or asking \"how do I make this effect\" — covers the vertex→fragment pipeline, UVs / normals / coordinate spaces, and per-engine authoring in Godot 4.x (shader_type spatial/canvas_item/particles, source_color, hint_screen_texture, ShaderMaterial), Unity 6 (Shader Graph vs HLSL, URP/HDRP, ShaderLab), and Unreal 5.x (Material graph, material domains, Custom HLSL node). Includes recipes for dissolve, rim/outline, toon/cel, water/flow, force field, hologram; full-screen post-process; and shader performance (overdraw, texture-sample cost, branching, mobile). Triggers: \"write a dissolve shader\", \"rim light\", \"toon shading\", \"screen-space effect\", \"my shader is slow on mobile\", \"cómo hago un shader de agua\". NOT gameplay or engine-API code (→ godot / unity / unreal) and NOT physics simulation, collision, or rigid bodies (→ gamedev-physics)."
+description: "Use when authoring or debugging a shader, material, VFX, or full-screen post-process in a game engine — Godot 4.x `.gdshader`, Unity 6 URP/HDRP, Unreal 5.x Materials, effect recipes, shader performance. NOT gameplay or engine-API code (that is `godot`/`unity`/`unreal`), NOT physics (`gamedev-physics`), NOT build variant stripping (`gamedev-shipping`)."
 tags: [shaders, vfx, materials, post-processing, shadergraph]
 recommends: [godot, unity, unreal, gamedev-shipping]
 profiles: [full]
@@ -11,8 +11,7 @@ origin: risco
 
 Author shaders, materials, and full-screen effects across Godot, Unity, and Unreal. One
 mental model — the GPU pipeline — mapped onto each engine's authoring surface, plus recipes
-for the effects people actually ask for. Fires on writing/debugging a shader or material,
-building a VFX/post-process effect, or "how do I make X look like Y".
+for the effects people actually ask for.
 
 ## Version contract — read first
 
@@ -28,22 +27,6 @@ symbol is current, say so rather than guess.
 `shader_type` tokens in Godot 4 are exact: `spatial`, `canvas_item` (underscore), `particles`
 (plural), `sky`, `fog`.
 
-## When to use / When NOT to use
-
-**Use when:** writing or debugging a `.gdshader`/`ShaderMaterial`, a `.shader`/Shader Graph, or
-a UE Material; building a VFX look (dissolve, rim, toon, water, shield, hologram, trails);
-authoring post-processing / screen-space effects; a shader is slow, flickers, or looks wrong;
-choosing per-vertex vs per-pixel; converting an effect between engines.
-
-**When NOT to use (delegate):**
-
-- Gameplay logic, nodes/components, input, engine APIs, scene setup → [`godot`](../godot/SKILL.md) /
-  [`unity`](../unity/SKILL.md) / [`unreal`](../unreal/SKILL.md). This skill owns the *shading*, not the C#/GDScript/Blueprint around it.
-- Physics simulation, collisions, rigid bodies, character controllers → [`gamedev-physics`](../gamedev-physics/SKILL.md).
-  (A shader that *fakes* refraction is here; simulating fluid dynamics is not.)
-- Shipping, platform export, shader-variant stripping in the build pipeline → [`gamedev-shipping`](../gamedev-shipping/SKILL.md)
-  (this skill keeps the per-shader performance work).
-
 ## Shader fundamentals (the pipeline)
 
 Every engine compiles your material into the same GPU stages. Two you write:
@@ -131,10 +114,10 @@ for high-end):
   blocks; the program goes in an `HLSLPROGRAM … ENDHLSL` block that `#include`s URP's `Core.hlsl`
   / `Lighting.hlsl`. Use for full control, custom lighting, or compute-driven effects.
 
-**Surface shaders are Built-in-RP only** — under URP/HDRP write a lit HLSL pass or a Shader Graph;
-use `TransformObjectToHClip` for the clip transform, not the retired `UnityObjectToClipPos`. Set
-parameters at runtime through a `MaterialPropertyBlock` or `Material.SetFloat/SetColor/SetTexture`.
-Full URP unlit + lit HLSL pass and a Shader Graph mapping → `references/unity-and-unreal-shaders.md`.
+Surface shaders are not an option under URP/HDRP (see the Version contract) — a lit look is an
+HLSL pass or a Shader Graph. Set parameters at runtime through a `MaterialPropertyBlock` or
+`Material.SetFloat/SetColor/SetTexture`. Full URP unlit + lit HLSL pass and a Shader Graph
+mapping → `references/unity-and-unreal-shaders.md`.
 
 ### Unreal 5.x
 
@@ -216,24 +199,27 @@ per engine → `references/effect-recipes.md`.
 - **Mobile / tile GPUs**: bandwidth-bound — keep render targets small, avoid mid-pass framebuffer
   reads, and note that `discard` and large full-screen passes break tile hidden-surface removal.
 
-## Guardrails / gotchas
+## Anti-patterns
 
-- Godot 4: the `SCREEN_TEXTURE`/`DEPTH_TEXTURE` built-ins are gone — declare `hint_screen_texture`
-  / `hint_depth_texture` uniforms. `hint_color` → `source_color`. Author colors as `source_color`
-  so sRGB→linear conversion is correct.
-- Unity: don't write a surface shader or include `UnityCG.cginc` for a URP/HDRP project.
-- Unreal: `SceneTexture` post-process nodes only work in the Post Process domain; match Opacity to
-  the blend mode.
-- Normalize interpolated normals per pixel; unpack normal maps (`×2−1`) and mind tangent handedness.
-- Watch color space (linear vs sRGB) at every texture read and color output — the #1 "looks washed
-  out / too dark" bug.
+| Anti-pattern | Do instead |
+| --- | --- |
+| Porting a tutorial verbatim from Godot 3, Built-in RP, or pre-5.0 UE | Translate it through the Version contract table first — retired symbols still compile in old guides, not in your project. |
+| Reading a texture or writing a color without minding linear vs sRGB | Author color uniforms as `source_color` (Godot) / sRGB-marked properties and check the space at every read and output — the #1 "looks washed out / too dark" bug. |
+| Using interpolated normals raw, or a normal map straight from the sample | Re-normalize per pixel; unpack with `×2−1` and mind tangent handedness. |
+| Writing the shader before choosing the target surface | Pick `shader_type` / render pipeline / material domain first (2D vs 3D, URP vs HDRP, Surface vs Post Process) — it decides which built-ins and blend modes exist. |
+| Fresnel, normalization, or lighting math in the vertex stage | Only linearly-interpolating work goes per-vertex; exact math stays per-pixel. |
+| `discard`/`clip` as a cheap "make it invisible" | Cull it or scale to zero — `discard` disables early-Z and breaks tile hidden-surface removal on mobile. |
+| Stacking additive/translucent layers until the look works | Count the overdraw: each layer re-shades the same pixels. Prefer opaque, minimize overlap, keep particle fill low. |
+| Full-screen effects via `OnRenderImage`/`Graphics.Blit`, or `SceneTexture` outside the Post Process domain | Use the engine's supported path — URP Renderer Feature / Fullscreen Shader Graph, UE Post Process material, Godot `ColorRect` + `hint_screen_texture` or `CompositorEffect`. |
 
 ## Related skills
 
-- [`godot`](../godot/SKILL.md) / [`unity`](../unity/SKILL.md) / [`unreal`](../unreal/SKILL.md) — the
-  engine skills own gameplay code, nodes/components, and scene wiring; this skill owns the shaders/materials.
-- [`gamedev-physics`](../gamedev-physics/SKILL.md) — simulation, collision, rigid bodies (a shader that *fakes* an effect stays here).
-- [`gamedev-shipping`](../gamedev-shipping/SKILL.md) — platform export and shader-variant stripping in the build.
+- [`godot`](../godot/SKILL.md) / [`unity`](../unity/SKILL.md) / [`unreal`](../unreal/SKILL.md) — gameplay
+  code, nodes/components, input, scene wiring; this skill owns the *shading*, not the C#/GDScript/Blueprint around it.
+- [`gamedev-physics`](../gamedev-physics/SKILL.md) — simulation, collision, rigid bodies, character
+  controllers (a shader that *fakes* refraction is here; simulating fluid dynamics is not).
+- [`gamedev-shipping`](../gamedev-shipping/SKILL.md) — platform export and shader-variant stripping in
+  the build (this skill keeps the per-shader performance work).
 
 ## Checklist
 
@@ -244,9 +230,3 @@ per engine → `references/effect-recipes.md`.
 - [ ] Uniforms/parameters exposed and driven from code or an animation track — not hard-coded.
 - [ ] Performance sanity: overdraw, sample count, and branching considered; mobile precision set if targeted.
 - [ ] Post-process uses the engine's supported full-screen path (not a retired Built-in-RP mechanism).
-
-## References
-
-- `references/godot-shading-language.md` — shader types, built-ins per type, render_modes, `varying`, screen/depth reads, ShaderMaterial from code.
-- `references/unity-and-unreal-shaders.md` — Unity URP HLSL pass + Shader Graph mapping; Unreal domains, Custom node HLSL, Material Instances.
-- `references/effect-recipes.md` — dissolve, rim/outline, toon/cel, water/flow, force field, hologram — full code per engine.

package/skills/gamedev-shaders/evals/cases.yaml

@@ -4,13 +4,13 @@ should_trigger:
   - prompt: "Write me a dissolve shader in Godot 4 that burns an object away from bottom to top with a glowing orange edge."
     why: "Dissolve is a named recipe and the core use case; Godot 4 .gdshader authoring is owned here."
   - prompt: "How do I make a rim light / fresnel glow on a 3D character in Unity URP?"
-    why: "Rim/fresnel is a named recipe; 'how do I make X effect' is an explicit trigger; Unity shader authoring is per-engine mapped here."
+    why: "Rim/fresnel is a named recipe; 'how do I make X effect' is the core shape of a shader request; Unity shader authoring is per-engine mapped here."
   - prompt: "My translucent particle shader tanks the framerate on mobile. How do I fix the overdraw?"
     why: "Shader performance — overdraw, transparency, mobile — is a dedicated section; symptom-only trigger routes here, not to a generic profiler."
   - prompt: "Set up a full-screen post-process effect in Unreal that reads scene depth and draws outlines."
     why: "Post-processing / full-screen effects per engine is a core section; Unreal Post Process material + SceneTexture is covered."
   - prompt: "Cómo hago un shader de agua con refracción y espuma en los bordes."
-    why: "Spanish water/flow recipe request; the description carries the Spanish 'cómo hago un shader de agua'."
+    why: "Spanish water/flow recipe request; water/flow is a named recipe and matching is by meaning, not by language."
   - prompt: "Convert this toon/cel shading effect from my Godot project to a Unity Shader Graph."
     why: "Toon/cel is a named recipe and cross-engine conversion is an explicit use case; the skill carries a Godot↔Unity↔Unreal map."
   - prompt: "What coordinate space are NORMAL and VIEW in inside a Godot spatial fragment shader, and why does my world-space fresnel look wrong?"

package/skills/gcp-essentials/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: gcp-essentials
-description: "Use when running a small product on the core of Google Cloud with the gcloud CLI: creating a project, deploying a container to Cloud Run, standing up a Cloud Storage bucket, a managed Cloud SQL Postgres/MySQL, and wiring them together with least-privilege IAM. Triggers: 'deploy to Cloud Run', 'gcloud run deploy', 'set up a GCP project', 'crear bucket en GCP', 'desplegar a Cloud Run', 'service account sin claves JSON', 'why is my Cloud Run running as the default service account', 'connect Cloud Run to Cloud SQL', 'turn off the bucket public access'. NOT AWS (that is aws-essentials)."
+description: "Use when running a small product on core Google Cloud via the gcloud CLI: a project, Cloud Run deploys, a locked-down Cloud Storage bucket, managed Cloud SQL, and least-privilege IAM wiring them together. NOT AWS (that is `aws-essentials`), NOT the CI pipeline that ships the image (that is `deployment`), NOT Postgres schema/query tuning (that is `postgresdb`)."
 tags: [gcp, cloud-run, cloud-sql, cloud-storage, iam, gcloud, serverless, devops]
 recommends: [aws-essentials, docker, github-actions, secure-coding, postgresdb, deployment, monitoring, backups]
 origin: risco
@@ -20,12 +20,14 @@ Four primitives carry most products, plus the project/billing scaffold under the
 - **Cloud Storage** — object storage (buckets).
 - **Cloud SQL** — managed Postgres/MySQL.
 
-Out of scope, route elsewhere: AWS -> `aws-essentials`. Building/shipping the image
-itself -> `docker` / `github-actions` / [`../deployment/SKILL.md`](../deployment/SKILL.md).
+Out of scope, route elsewhere: AWS -> [`../aws-essentials/SKILL.md`](../aws-essentials/SKILL.md).
+Building/shipping the image itself -> [`../docker/SKILL.md`](../docker/SKILL.md)
+/ [`../github-actions/SKILL.md`](../github-actions/SKILL.md) / [`../deployment/SKILL.md`](../deployment/SKILL.md).
 Postgres schema/index/query tuning -> [`../postgresdb/SKILL.md`](../postgresdb/SKILL.md).
 App-level injection/secret-handling review -> [`../secure-coding/SKILL.md`](../secure-coding/SKILL.md).
-Logging/alerting/SLOs as a practice -> `monitoring`. Backup strategy as a discipline
--> `backups`. One-click PaaS where you never touch IAM/VPC -> [`../vercel/SKILL.md`](../vercel/SKILL.md)
+Logging/alerting/SLOs as a practice -> [`../monitoring/SKILL.md`](../monitoring/SKILL.md).
+Backup strategy as a discipline -> [`../backups/SKILL.md`](../backups/SKILL.md).
+One-click PaaS where you never touch IAM/VPC -> [`../vercel/SKILL.md`](../vercel/SKILL.md)
 / [`../railway/SKILL.md`](../railway/SKILL.md) / [`../render/SKILL.md`](../render/SKILL.md)
 / [`../fly-io/SKILL.md`](../fly-io/SKILL.md).
 
@@ -96,8 +98,8 @@ Two hard rules, each with teeth:
    Identity Federation for external/CI auth (GitHub Actions). If `... keys create` is
    in your runbook, the runbook is wrong.
 
-WIF for keyless CI, SA impersonation, IAM Recommender and Conditions live in
-[`references/iam-and-auth.md`](references/iam-and-auth.md).
+The predefined-role catalog, WIF for keyless CI, SA impersonation, IAM Recommender and
+Conditions live in [`references/iam-and-auth.md`](references/iam-and-auth.md).
 
 ## 2. Cloud Run
 
@@ -233,8 +235,9 @@ gcloud run deploy api --region=europe-west1 \
 ```
 
 The Cloud SQL **Auth Proxy** (short-lived certs, TLS 1.3) is for connecting from
-*outside* — local dev or a non-serverless host — not for Cloud Run. Private IP, PSC
-and proxy invocation are in [`references/networking-and-sql.md`](references/networking-and-sql.md).
+*outside* — local dev or a non-serverless host — not for Cloud Run. Direct VPC egress vs
+legacy connectors, private IP / PSC, proxy invocation and pooling are in
+[`references/networking-and-sql.md`](references/networking-and-sql.md).
 
 ## 5. Wire it together
 
@@ -267,6 +270,10 @@ Note the scoping: `cloudsql.client` is project-wide (the role needs it), but the
 storage and secret grants are bound to the *specific* bucket and secret, not the
 project. Grant narrow.
 
+Copy-paste runbooks for each piece — image build and push, private container deploy,
+attach SQL, mount a secret, full teardown — are in
+[`references/deploy-recipes.md`](references/deploy-recipes.md).
+
 ## 6. Cost & teardown
 
 - Cloud Run scales to zero by default — an idle service costs ~nothing. Keep
@@ -315,13 +322,3 @@ bash scripts/verify.sh path/to/dir/              # recurse a directory
 
 It prints `PASS`/`FAIL` per check and exits nonzero on any FAIL. An empty or
 clean target passes (exit 0).
-
-## References
-
-- [`references/iam-and-auth.md`](references/iam-and-auth.md) — predefined-role catalog,
-  Workload Identity Federation for GitHub Actions, SA impersonation, IAM Recommender,
-  Conditions.
-- [`references/networking-and-sql.md`](references/networking-and-sql.md) — Direct VPC
-  egress vs legacy connectors, Cloud SQL private IP / PSC, Auth Proxy, pooling.
-- [`references/deploy-recipes.md`](references/deploy-recipes.md) — copy-paste runbooks:
-  container deploy, attach SQL, mount a secret, budget alert, full teardown.

package/skills/hetzner/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: hetzner
-description: "Use when provisioning or hardening a Hetzner Cloud VPS to host real apps: picking a plan/location (CX/CPX/CAX/CCX), bringing a box up reproducibly with the hcloud CLI + cloud-init, locking down SSH, and wiring the Hetzner Cloud Firewall before handing off a Docker/Coolify-ready host. Triggers: 'set up a Hetzner server', 'provision a Hetzner VPS', 'harden SSH on my box', 'which Hetzner plan for a small API', 'configure the Hetzner Cloud Firewall', the non-obvious 'my ipv6-only box is cheaper but docker pull can't reach the registry', and the Spanish/Catalan 'monta un servidor en Hetzner', 'configura el firewall de Hetzner'. NOT deploying apps through Coolify (that is coolify)."
+description: "Use when provisioning or hardening a Hetzner Cloud VPS: picking the plan/location (CX/CPX/CAX/CCX), bringing it up reproducibly with hcloud + cloud-init, locking down SSH, and wiring the Cloud Firewall to hand off a Docker-ready host. NOT app deploys on Coolify (that is `coolify`), NOT Dockerfiles (that is `docker`), NOT another provider (that is `digitalocean`)."
 tags: [hetzner, vps, cloud-firewall, hcloud, ssh-hardening, cloud-init, self-hosting]
 recommends: [coolify, docker, secure-coding, domains-dns, backups, monitoring]
 origin: risco
@@ -14,17 +14,8 @@ include 20 TB of egress. The risk is that "cheap" becomes "unhardened and
 unmonitored" — a root-SSH box on a public IPv4 with password auth on. Your job
 is to make the cheap box **safe** and **reproducible**: every server comes up
 from a committed cloud-init file and a Cloud Firewall ruleset, never from
-click-ops in the console.
-
-Operating posture:
-
-- **Reproducible by default.** A box you can't recreate from a file isn't a box,
-  it's a pet. Bake the non-root user, SSH key, and sshd hardening into first
-  boot via cloud-init — not into a post-login checklist you'll forget.
-- **Two firewalls, edge first.** The Hetzner Cloud Firewall stops packets before
-  they reach the VM; host `ufw` is defense-in-depth. You need both.
-- **Honest about the trade-off.** No managed DB, no uptime SLA, phone support
-  only for dedicated-server customers. Name it; don't pretend it's AWS.
+click-ops in the console. A box you can't recreate from a file isn't a box, it's
+a pet.
 
 ## Decide before you create
 
@@ -139,8 +130,8 @@ hcloud firewall add-rule    app-edge --direction in --protocol tcp --port 22 --s
 
 ## SSH hardening rules
 
-- **Key-only auth.** `PasswordAuthentication no`. A password is brute-forceable;
-  an ed25519 key is not.
+- **Key-only auth.** `PasswordAuthentication no`, `PubkeyAuthentication yes`. A
+  password is brute-forceable; an ed25519 key is not.
 - **No root login.** `PermitRootLogin no` + a sudo user. Root over SSH is the
   single most-targeted login on the internet.
 - **fail2ban on.** Bans IPs after repeated failures — cheap insurance for the
@@ -149,16 +140,6 @@ hcloud firewall add-rule    app-edge --direction in --protocol tcp --port 22 --s
   harden anything. Do it if you like clean logs, but never *instead* of key-only
   + a firewall.
 
-Bad → Good:
-
-```diff
-- PermitRootLogin yes
-- PasswordAuthentication yes
-+ PermitRootLogin no
-+ PasswordAuthentication no
-+ PubkeyAuthentication yes
-```
-
 ## Hand off to Docker / Coolify
 
 "Host ready" means all of the following are true:
@@ -169,28 +150,29 @@ Bad → Good:
 - [ ] `ufw status` enabled with the same allowlist.
 - [ ] `unattended-upgrades` and `fail2ban` running.
 
-Then route the install/deploy: Coolify (the self-hosted PaaS) and container
-build/run are not this skill's job. Use the `coolify` skill for the Coolify
-install + app deploy flow, and the `docker` skill for Dockerfiles, compose, and
-image hardening. This skill stops at a clean, hardened host.
+This skill stops at a clean, hardened host. Then route the install/deploy:
+[`coolify`](../coolify/SKILL.md) for the Coolify install + app deploy flow,
+[`docker`](../docker/SKILL.md) for Dockerfiles, compose, and image hardening.
 
 ## Day-2
 
 - **Snapshot ≠ backup.** A snapshot is a one-off manual image you can boot from;
   the **Backups** add-on is automated, rotating, ~20% of the server price. A
-  snapshot you took once in March is not a backup strategy — for that, see the
-  `backups` skill.
+  snapshot you took once in March is not a backup strategy — for that, see
+  [`backups`](../backups/SKILL.md).
 - **Resize grows, never shrinks.** You can scale the disk up; you cannot scale it
   back down. Size conservatively or you're stuck paying for it.
 - **Volumes** for data you want to outlive/detach from the server. Keep databases
   and uploads on a volume so a server rebuild doesn't take the data with it.
 - **Reverse DNS** must match for outbound mail to be accepted — set the PTR in the
-  console/`hcloud` if the box sends email. Forward DNS records belong to the
-  `domains-dns` skill.
-- **No SLA, no managed DB.** There's no uptime guarantee and no managed-database
-  product — you run Postgres yourself, you monitor it yourself. For monitoring
-  and alerting, see the `monitoring` skill; treat the box as something you must
-  watch, not something Hetzner watches for you.
+  console/`hcloud` if the box sends email. Forward DNS records belong to
+  [`domains-dns`](../domains-dns/SKILL.md).
+- **No SLA, no managed DB.** There's no uptime guarantee, no managed-database
+  product, and phone support only for dedicated-server customers — you run
+  Postgres yourself, you monitor it yourself. For monitoring and alerting, see
+  [`monitoring`](../monitoring/SKILL.md); treat the box as something you must
+  watch, not something Hetzner watches for you. Name the trade-off to the user;
+  don't pretend it's AWS.
 
 ## Anti-patterns
 

package/skills/knowledge-ops/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: knowledge-ops
-description: "Use when an already-running 02-DOCS/ wiki needs day-to-day gardening — too many half-finished articles, a 600-line page that covers three unrelated topics, a note with no obvious home, orphan pages nothing links to, stale answers and superseded articles piling up, or two articles that contradict each other. This is the judgment layer over harness's automation: decide what is worth capturing (default: nothing), where it goes, how to title/split/merge it, build the See Also web, and prune to _archive (never delete). Triggers: 'limpia mi wiki', 'organiza mis notas', 'esto dónde va en la wiki', 'ordena la base de conocimiento', 'split this bloated article', 'where should this note live', 'scores.json says these three are orphans — fix the cross-links', 'prune the stale and superseded stuff'. NOT building, bootstrapping or sweeping the wiki engine (that is harness)."
+description: "Use when an already-running 02-DOCS/ wiki needs gardening judgment — what is worth capturing (default: nothing), where a loose note belongs, whether to split a bloated article or merge near-duplicates, how to link orphans back in, and what retires to _archive (never delete). NOT building or sweeping the wiki engine itself (that is `harness`)."
 tags: [knowledge-ops, wiki, 02-docs, knowledge-base, curation, cross-linking, pruning, knowledge-meta]
 recommends: [harness, decision-records, meeting-notes, sop-builder, research-ops, codebase-onboarding]
 origin: risco
@@ -8,7 +8,7 @@ origin: risco
 
 # Knowledge Ops — Garden the 02-DOCS Wiki
 
-*The engine is already running. `harness` built the `02-DOCS/` wiki and owns its automation — the inbox sweep, deterministic lint, scoring, gap detection, the self-improve loop. Your job is the four judgments that automation deliberately leaves to a human: what is worth capturing, how it should be shaped, how it connects, and what should retire. You are the gardener, not the machinery.*
+*The engine is already running. `harness` built the `02-DOCS/` wiki and owns its automation — the inbox sweep, deterministic lint, scoring, gap detection, the self-improve loop — and changing that machinery or filling the wiki in bulk stays with it. Yours are the four judgments automation deliberately leaves to a human: what is worth capturing, how it should be shaped, how it connects, and what should retire. You are the gardener, not the machinery.*
 
 ## Before you touch anything
 
@@ -29,7 +29,7 @@ Every gardening request is one of four operations. Identify which before you act
 | **Link** | Pages are unreachable or under-connected | `scores.json` orphan_penalty (=5), low inbound count | `## See Also` in articles, `index.md` |
 | **Prune** | Answers are stale, articles superseded, conflicts unresolved, gaps bloated | freshness, conflict annotations, old `[FILLED]` gaps | `_archive/`, `log.md`, `gaps.md` |
 
-Whichever you do, record a line in `wiki/log.md`. `log.md` is the OKF reserved change-log: new entries are **prepended at the top (newest first)**, ISO 8601 dates, and past entries are never edited or deleted. (`gaps.md` is the append-only file — new entries go at the bottom.) The exact entry shapes per operation live in `references/gardening-playbook.md`.
+Whichever you do, record a line in `wiki/log.md` under the reserved-file rule in **Safety rails** below. The exact entry shapes per operation live in `references/gardening-playbook.md`.
 
 ## Capture — the bar is high
 
@@ -44,7 +44,7 @@ Walk the altitude ladder, lowest rung first; stop at the first that fits:
 
 Worked examples for each rung are in `references/gardening-playbook.md`.
 
-**Topic choice.** Reuse an existing topic before inventing one, and keep `wiki/` exactly **one level of subdirs** deep (the protocol's rule). 
+**Topic choice.** Reuse an existing topic before inventing one, and keep `wiki/` exactly **one level of subdirs** deep (the protocol's rule).
 
 - Bad: `wiki/payments/stripe/webhooks/retries.md` (four levels deep).
 - Good: `wiki/payments/stripe-webhook-retries.md` (existing `payments/` topic, one level).
@@ -81,20 +81,19 @@ Every article earns **≥1 inbound link** or is a conscious leaf you can justify
 
 - **Conflicts:** you **flag** contradictions and the **human arbitrates**. Once they choose a winner, you may apply the resolution and annotate the loser — but you never auto-pick. Why: silently choosing a side is data corruption.
 - **Stale answers:** mark a page or archived copy with a `> ⚠ Stale — superseded YYYY-MM-DD` note rather than rewriting history.
-- **Compaction is bounded:** only `[FILLED YYYY-MM-DD]` gaps **older than 90 days** may be compacted, and only via a single marker prepended to `log.md`. `gaps.md` is append-only and `log.md` is newest-first (both immutable past entries) — gaps get a `[FILLED]` stamp, never a deletion.
-- **Log every prune** by prepending to `wiki/log.md` (newest first). Exact entry shapes per operation: `references/gardening-playbook.md`.
+- **Compaction is bounded:** only `[FILLED YYYY-MM-DD]` gaps **older than 90 days** may be compacted, and only via a single marker prepended to `log.md` — a gap gets a `[FILLED]` stamp, never a deletion.
+- **Log every prune** by prepending to `wiki/log.md`.
 
-A full worked prune session (stale + superseded + conflict + gap compaction, all logged) is in the playbook.
+A full worked prune session (stale + superseded + conflict + gap compaction, all logged) is in `references/gardening-playbook.md`.
 
-## Safety rails (inherited from the protocol)
+## Safety rails
 
-These are hard constraints, not suggestions. They come from `../harness/references/wiki-protocol.md` — do not override them.
+Inherited from `../harness/references/wiki-protocol.md` — do not override them; each one guards against a loss you cannot undo.
 
 1. **Preserve before overwrite.** Never overwrite an article without first copying the old version to `wiki/<topic>/_archive/<article>__YYYY-MM-DD.md`.
 2. **Never auto-resolve a conflict.** Flag it; the human arbitrates.
-3. **`gaps.md` is append-only; `log.md` is newest-first.** New `gaps.md` entries are appended at the bottom; new `log.md` entries are prepended at the top (the OKF reserved-file rule). Past entries in either are immutable — gaps get `[FILLED YYYY-MM-DD]`, nothing is ever edited out.
-4. **Log every change** by prepending to `wiki/log.md` (newest first).
-5. **Never touch an article whose `timestamp` is < 24h ago** without explicit user say-so. Why: it is likely still being worked. (`timestamp` is the OKF last-meaningful-edit field, ISO 8601 — see `../harness/references/wiki-protocol.md` "## Conventions".)
+3. **The reserved files only grow.** Log every change in `wiki/log.md`, the OKF reserved change-log: new entries are **prepended at the top (newest first)**, ISO 8601 dates. `gaps.md` is the append-only one — new entries go at the bottom. Past entries in either are immutable: a gap gets a `[FILLED YYYY-MM-DD]` stamp, nothing is ever edited out or deleted.
+4. **Never touch an article whose `timestamp` is < 24h ago** without explicit user say-so. Why: it is likely still being worked. (`timestamp` is the OKF last-meaningful-edit field, ISO 8601 — see `../harness/references/wiki-protocol.md` "## Conventions".)
 
 ## Anti-patterns
 
@@ -117,9 +116,7 @@ Route elsewhere when the request is not gardening an existing wiki:
 |---------|----------|
 | Build/bootstrap the wiki, run an inbox sweep, scaffold `01-TOOLS`, generate root `CLAUDE.md` | `harness` (`../harness/SKILL.md`) — it owns the engine |
 | Turn a meeting transcript into a recap with action items + owners | `meeting-notes` (`../meeting-notes/SKILL.md`) |
-| Author a decision record (ADR) with alternatives, status, review cadence | `decision-records` (you may *file* one; that skill *authors* the discipline) |
+| Author a decision record (ADR) with alternatives, status, review cadence | `decision-records` (`../decision-records/SKILL.md`) — you may *file* one; that skill *authors* the discipline |
 | Document a repeatable procedure step by step | `sop-builder` (`../sop-builder/SKILL.md`) |
-| First-pass walkthrough of an unfamiliar codebase | `codebase-onboarding` |
-| Run a literature / source-gathering research project | `research-ops` |
-
-The sharp line: changing the wiki's machinery or filling it in bulk is `harness`. Exercising judgment over what an already-running wiki should contain and how it should be shaped is `knowledge-ops`.
+| First-pass walkthrough of an unfamiliar codebase | `codebase-onboarding` (`../codebase-onboarding/SKILL.md`) |
+| Run a literature / source-gathering research project | `research-ops` (`../research-ops/SKILL.md`) |

package/skills/medium-publishing/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: medium-publishing
-description: "Use when getting a finished article onto Medium correctly — choosing profile vs publication, cross-posting from your own site without an SEO duplicate-content hit, the import tool, the 5-tag limit, and Medium's pseudo-Markdown formatting gotchas. Triggers: 'cross-post to Medium', 'republish on Medium with a canonical link', 'submit my draft to a Medium publication', 'why are my code blocks broken on Medium', 'can I still automate Medium via the API', 'the Medium import tool failed with a 403', 'importar mi artículo a Medium sin penalización SEO', 'publicar a Medium amb enllaç canònic'. NOT drafting, structuring, or headlining the article itself (that is medium-writing)."
+description: "Use when a finished article has to land on Medium correctly — profile vs publication, cross-posting under a canonical link so your own site keeps the SEO credit, import-tool failures, the 5-tag cap, pseudo-Markdown gotchas. NOT writing or headlining the piece (that is `medium-writing`), NOT cadence or earnings (that is `medium-strategy`)."
 tags: [medium, publishing, cross-posting, canonical-url, seo, import-tool]
 recommends: [medium-writing, medium-strategy, seo-geo, social-publisher]
 origin: risco
@@ -10,13 +10,11 @@ origin: risco
 
 Land a finished article on Medium with correct metadata: right destination, no duplicate-content penalty, valid tags, intact formatting. Writing the article is `../medium-writing/SKILL.md`; deciding when/where/how-often to publish and how it grows is `../medium-strategy/SKILL.md`. This skill is only the mechanics of getting bytes onto the platform with the right metadata attached.
 
-## Reality check — read this first (2025-2026)
+## Reality check (2025-2026)
 
 **The Medium API is closed to new integrations.** As of 2025-01-01 Medium issues no new integration tokens and accepts no new integrations; only tokens minted before that date still work. Why it matters: any plan that starts with "register a Medium API token and automate it" is dead on arrival for anyone who didn't already have one. Integration platforms confirm this — the Medium app in Make is marked legacy, and n8n's Medium credentials can no longer be newly configured.
 
-So the default publishing path is **web editor + import tool + canonical link**, done through the UI. Treat the API as a legacy escape hatch (last section), not the plan.
-
-Do not promise API automation. If the user asks "can I get a token and automate this?", the honest answer is almost always no — explain why and route them to the import path below.
+So the default publishing path is **web editor + import tool + canonical link**, done through the UI. Treat the API as a legacy escape hatch (last section), not the plan — when asked "can I get a token and automate this?", the honest answer is almost always no, so say why and route to the import path below rather than promising automation.
 
 ## Decision table — pick your path
 
@@ -30,11 +28,9 @@ Branch on where the article already lives and what you control:
 | You hold a pre-2025 API token and want automation | Legacy `POST /v1/users/{id}/posts` | `canonicalUrl` field in the request body |
 | Destination is a publication you write for | Submit draft to the publication | Same as above; submission is separate from canonical |
 
-When in doubt and the piece exists elsewhere, prefer the import tool — it gets canonical *and* backdate right in one step.
-
 ## Cross-post without an SEO penalty (the core job)
 
-When the article already lives on your own site, you must tell search engines the original is canonical, or Google sees two copies and may credit Medium or neither. Two mechanisms, in order of preference:
+When the article already lives on your own site, you must tell search engines that the **origin** — your page, never the Medium URL — is canonical, or Google sees two copies and may credit Medium or neither. Two mechanisms, in order of preference:
 
 **1. Import tool (preferred).** Pasting the original URL into Medium's import field does three things at once:
 - imports the rendered content into a new draft,
@@ -54,8 +50,6 @@ Good: Use the import tool (canonical + backdate set automatically), or if
       BEFORE publishing.
 ```
 
-The canonical must point to the **origin** (your site), not to the Medium URL. The whole point is that your site keeps the SEO credit.
-
 ## When the import fails
 
 The importer is an HTTP crawler hitting your URL; failures are crawl failures, not Medium bugs. Map the symptom to the cause:
@@ -98,9 +92,7 @@ Good: Convert the table to a labeled list, or screenshot/export it as an
 Two outcomes, often confused:
 
 - **Self-publish** puts the story on your own profile immediately.
-- **Submit to a publication** routes the draft to that publication's editors. It stays **pending** — not live — until an editor publishes it, and you must already be an accepted writer for that publication. Submitting does not auto-publish.
-
-Why it sits pending: a publication is editorially controlled; submission is a request, not a publish action. If you're not yet a writer there, request access first; submitting otherwise goes nowhere.
+- **Submit to a publication** routes the draft to that publication's editors, where it stays **pending** — not live — until one of them publishes it. A publication is editorially controlled, so submission is a request, not a publish action, and it only works if you are already an accepted writer there. If you're not, request access first; submitting otherwise goes nowhere.
 
 ## Legacy API — only if you hold a pre-2025 token
 

package/skills/n8n/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: n8n
-description: "Use when operating a live n8n instance programmatically — driving its public REST API (`{host}/api/v1`, `X-N8N-API-KEY`) or the n8n-mcp server to create, validate, test, activate/deactivate, list, update, or delete workflows and read executions, on self-host or `*.app.n8n.cloud`. Triggers: 'deploy this workflow to my n8n over the API', 'push my workflow JSON to n8n with curl', 'I set active:true in the create call but it stays inactive', 'connect n8n-mcp / n8n_create_workflow to Claude', 'validate and autofix my n8n workflow', 'run an n8n workflow by id from a script', 'delete a workflow via the API', 'automatiza n8n por API', 'desplega el workflow a n8n.cloud'. NOT designing the flow's trigger-step-error logic or hand-building the importable workflow JSON (that is automation-flows), NOT operating Make / Zapier / Power Automate (their own skills), NOT a typed API client with auth+pagination+retry (api-connector-builder), NOT the inbound webhook receiver in your own app (webhooks)."
+description: "Use when operating a live n8n instance programmatically — its REST API (`{host}/api/v1`, `X-N8N-API-KEY`) or the n8n-mcp server — to create, validate, test, activate, update, delete workflows and read executions on self-host or n8n.cloud. NOT designing the flow or its importable JSON (that is `automation-flows`), NOT another platform (`make`, `zapier`)."
 tags: [n8n, automation, workflows, mcp, rest-api, no-code, integrations]
 recommends: [automation-flows, automation-strategy, api-connector-builder, webhooks]
 profiles: [full]
@@ -9,15 +9,11 @@ origin: risco
 
 # n8n — operate a live instance over its REST API and MCP
 
-You already have a workflow *design* (the trigger→steps→error shape and the importable JSON).
-This skill is the **operate** half: push that JSON into a running n8n, validate it, test it, flip it
-live, watch its executions, and tear it down safely — all without touching the UI. n8n has the
-richest programmatic story of the no-code platforms: a first-party REST API **plus** a mature MCP
-server, both hitting the same instance.
-
-Designing the flow itself (what fires it, how errors are handled, dedup) is **automation-flows** —
-this skill *consumes* that skill's `references/n8n-workflow-json.md` payload; it does not re-teach
-design.
+You already have a workflow *design* — the trigger→steps→error shape and the importable JSON, which is
+`automation-flows`' job and this skill does not re-teach it. This skill is the **operate** half: push
+that JSON into a running n8n, validate it, test it, flip it live, watch its executions, and tear it
+down safely — all without touching the UI. n8n has the richest programmatic story of the no-code
+platforms: a first-party REST API **plus** a mature MCP server, both hitting the same instance.
 
 ## Connect first — REST API vs MCP
 
@@ -31,10 +27,10 @@ Two ways to drive the same instance. Pick by who is at the wheel.
 | Surface | identical on self-host **and** `*.app.n8n.cloud` | same underlying API; hosted trial at `dashboard.n8n-mcp.com` |
 
 **Version reality (verify at author time — n8n moves fast):**
-- API base is `{host}/api/v1`. Self-host ships interactive Swagger at `/api/v1/docs`; **cloud does not**.
+- API base is `{host}/api/v1`. Self-host ships interactive Swagger at `/api/v1/docs`; **cloud does not**
+  — on cloud, work from the docs.
 - `POST /workflows/{id}/execute` (run-by-id) is **recent** (n8n PR #20234). Older instances lack it —
-  there, the only programmatic run is POSTing to a Webhook node's URL. It also takes **no custom input**.
-- The API surface is the SAME whether you self-host or run on `*.app.n8n.cloud`; only the host differs.
+  there, the only programmatic run is POSTing to a Webhook node's URL.
 
 ### `.env`
 
@@ -66,7 +62,8 @@ shapes rather than guessing — that is the single biggest reason to drive via M
 ## Dynamic lifecycle
 
 create → **validate** → test → **activate** → manage → delete. A concrete sketch per step, curl and
-n8n-mcp side by side.
+n8n-mcp side by side; every endpoint with pagination and scopes is in
+`references/rest-api-cheatsheet.md`.
 
 ### 1. Validate (do this BEFORE create)
 
@@ -107,8 +104,9 @@ n8n_test_workflow       { "id": "$ID" }
 
 ### 4. Activate — the step people miss
 
-`active` in the create/update body is **read-only and silently ignored**. Setting `"active": true`
-does nothing. You MUST call the separate endpoint:
+`active` (and `tags`) in the create/update body are **read-only and silently ignored**. Setting
+`"active": true` does nothing, which is why the workflow you just created never fires. You MUST call
+the separate endpoint:
 
 ```bash
 curl -sS -X POST "$N8N_API_URL/api/v1/workflows/$ID/activate"   -H "X-N8N-API-KEY: $N8N_API_KEY"
@@ -137,7 +135,8 @@ omitted. n8n-mcp's `n8n_update_partial_workflow` applies a targeted, atomic batc
 
 ### 6. Delete — irreversible
 
-`DELETE` is a **hard delete: no trash, no undo.** Export the current JSON first, every time.
+`DELETE` is a **hard delete: no trash, no undo**, so export the current JSON first, every time — this
+one is absolute because nothing downstream can recover the workflow if you skip it.
 
 ```bash
 curl -sS "$N8N_API_URL/api/v1/workflows/$ID" -H "X-N8N-API-KEY: $N8N_API_KEY" > backup-$ID.json  # export FIRST
@@ -147,7 +146,7 @@ curl -sS -X DELETE "$N8N_API_URL/api/v1/workflows/$ID" -H "X-N8N-API-KEY: $N8N_A
 n8n_get_workflow { "id": "$ID" }   →  save output  →  n8n_delete_workflow { "id": "$ID" }
 ```
 
-**Irreversibility rule:** never DELETE (or full-replace) a live workflow without exporting it first.
+The same applies to a full replace: export before `PUT`.
 
 ## Governance
 
@@ -156,50 +155,23 @@ If you expose n8n-mcp to an agent, lock down destructive tools with the `DISABLE
 key itself too — n8n supports scoped keys (e.g. grant `workflow:read` without `workflow:execute`).
 Details in `references/n8n-mcp-tools.md`.
 
-## Honesty / gotchas
-
-- **`active` and `tags` are read-only on create/update** — ignored in the body; activate/tag via the
-  dedicated endpoints. This is the #1 "why is my workflow inactive" bug.
-- **`/workflows/{id}/execute` takes no custom input** — for runtime params, trigger a Webhook workflow
-  by POSTing to its URL. Also, it is a newer endpoint; older instances 404 it.
-- **`DELETE` and `PUT` are destructive** — hard delete (no trash) and full replace. Export first; prefer
-  `n8n_update_partial_workflow` for edits.
-- **`typeVersion` must exist on the target** — a node version the instance doesn't have fails only at
-  activate/execute time, not at create. Validate (MCP) or test before activating.
-- **Credential secrets are not fully manageable over the public API** — you can reference existing
-  credentials by id/name and create some, but you cannot read secrets back; provision credentials in
-  the UI / n8n-mcp `n8n_manage_credentials` and reference them.
-- **Cloud has no Swagger** — `/api/v1/docs` is self-host only; on cloud, work from the docs.
-- **Activation can succeed via API where the UI would block it** — the public API historically skips a
-  few UI-side activation validations, so a workflow can be "active" yet non-functional. Test it live.
-
-## Related skills
-
-- **automation-flows** — *design* the flow and produce the importable JSON this skill deploys. Design
-  vs operate boundary: they decide the trigger/steps/error path; you push it live. Start there if the
-  flow's logic isn't settled yet.
-- **automation-strategy** — whether n8n is even the right platform (cost model, self-host vs cloud) vs
-  Make/Zapier/Power Automate.
-- **make / zapier / power-automate** — the other platforms' operate stories (Zapier and Power Automate
-  can't create flows via API — n8n's edge).
-- **api-connector-builder** — a generic typed HTTP client with auth/pagination/backoff, when the answer
-  is real code, not a workflow.
-- **webhooks** — building the inbound receiver *in your own app*; here webhooks are just n8n triggers.
-
-## Checklist
-
-- [ ] `.env` has `N8N_API_URL`/`N8N_HOST` + `N8N_API_KEY` (key from Settings → n8n API); key not logged.
-- [ ] Payload has `name`, `nodes` (one trigger), `connections`, `settings` per automation-flows' schema;
-      node credentials referenced by store, never inlined.
-- [ ] Validated (`n8n_validate_workflow` / `n8n_autofix_workflow`) before create when MCP is available.
-- [ ] Created via `POST /workflows` or `n8n_create_workflow`; captured the returned `id`.
-- [ ] Tested — `execute`-by-id (no input) or POST to the webhook URL (with input) — and the run succeeded.
-- [ ] Activated via `POST /workflows/{id}/activate` (NOT `active:true` in the body).
-- [ ] Before any DELETE or full-replace: exported the current JSON (hard delete, no trash).
-- [ ] If MCP is exposed to an agent: `DISABLED_TOOLS` set and/or the API key scoped.
-
-## References
-
-- `references/rest-api-cheatsheet.md` — every workflow/execution endpoint with curl, pagination, scopes.
-- `references/n8n-mcp-tools.md` — the management + node-knowledge tool list, the auth split, `DISABLED_TOOLS`.
-- `references/auth-and-selfhost.md` — API-key creation, self-host vs cloud, Swagger, installing/pointing n8n-mcp.
+## Anti-patterns
+
+| Anti-pattern | Why it bites | Do instead |
+|---|---|---|
+| `"active": true` (or `tags`) in the create/update body | Read-only fields, silently ignored — the #1 "why is my workflow inactive" bug | `POST /workflows/{id}/activate`; set tags via their own endpoint |
+| Passing runtime input to `/workflows/{id}/execute` | It accepts no custom input, and older instances 404 the endpoint entirely | Trigger a Webhook workflow by POSTing to its URL |
+| `PUT` with a partial body, or `DELETE` on a live workflow | Full replace drops every node you omitted; delete is a hard delete with no trash | GET and export first; prefer `n8n_update_partial_workflow` for edits |
+| A `typeVersion` the target instance doesn't have | Create succeeds; it fails only at activate/execute time | Validate via MCP, or test, before activating |
+| Inlining node credential secrets, or expecting to read them back | Credentials are not fully manageable over the public API — it can create some, but never returns a secret | Provision in the UI or via `n8n_manage_credentials`, then reference existing credentials by id/name |
+| Treating a successful API activation as proof it works | The public API historically skips a few UI-side activation validations, so a workflow can be "active" yet non-functional | Run it live after activating and check the execution |
+
+## Route elsewhere
+
+| If the ask is | Skill |
+|---|---|
+| Designing the flow (trigger/steps/error path, dedup) and producing the importable JSON | `automation-flows` — start there if the logic isn't settled |
+| Whether n8n is the right platform at all — cost model, self-host vs cloud | `automation-strategy` |
+| Operating a different platform | `make`, `zapier`, `power-automate` (neither Zapier nor Power Automate can create flows via API — n8n's edge) |
+| A generic typed HTTP client with auth/pagination/backoff — real code, not a workflow | `api-connector-builder` |
+| The inbound webhook receiver in your own app (here webhooks are only n8n triggers) | `webhooks` |

package/skills/notion-connector/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: notion-connector
-description: "Use when wiring an app, cron job, or service to Notion as an ops backend over the official HTTP API — pushing rows into a Notion database, mirroring a database into your app, syncing both ways without duplicates, building or reading page block content, or fixing an integration that broke after the 2025-09-03 data-source split. Triggers: 'store our tasks in a Notion database from code', 'use Notion as a CRM/content calendar', 'sync our CRM into Notion nightly without duplicates', 'why does POST /v1/databases/:id/query return 404 now', 'integration broke after a teammate added a second data source', 'guardar registros en una base de datos de Notion desde código', 'desar files a una base de dades de Notion'. NOT a generic call-any-REST-API integration (that is api-connector-builder), NOT receiving/verifying inbound Notion webhook events (that is webhooks)."
+description: "Use when wiring server code or a cron job to Notion as an ops backend over its HTTP API: pushing or mirroring database rows, two-way sync without duplicates, page blocks, or an integration broken by the 2025-09-03 data-source split. NOT generic REST wiring (that is `api-connector-builder`), NOT inbound Notion webhook events (that is `webhooks`)."
 tags: [notion, ops-backend, api-integration, databases, sync]
 recommends: [api-connector-builder, webhooks, automation-flows, spreadsheet-ops, secure-coding]
 origin: risco
@@ -14,24 +14,7 @@ write page blocks. This skill owns the **outbound** Notion API surface only —
 the database/data-source data model, property-type write shapes, and the
 rate-limit/pagination discipline that the API forces on you.
 
-## The one rule
-
-**Pin the `Notion-Version` per request, and resolve the data source before you
-query.** Post `2025-09-03` a database is a *container* of one or more data
-sources — not a queryable table. Skip either half and you get silent 404s on
-code that worked last year.
-
-- Current major version: **`2025-09-03`** (the SDK default). Latest: **`2026-03-11`**.
-- Behavior differs across versions; an unpinned client drifts when the default moves.
-
-## When to use / when NOT to use
-
-**Use when:** treating a Notion database as a CRM / task tracker / content
-calendar from code; pushing or pulling rows on a schedule; two-way sync that
-must not duplicate on re-run; building or reading page block content; migrating
-a `2022-06-28` integration that broke when someone added a second data source.
-
-**Route elsewhere:**
+## Route elsewhere
 
 | Situation | Route to |
 |---|---|
@@ -50,10 +33,12 @@ a `2022-06-28` integration that broke when someone added a second data source.
 3. **Share the target database/page with the integration** in the Notion UI
    (the page `•••` menu → Connections). *Skip this and every call 404s or
    returns empty* — the integration sees nothing it was not explicitly granted.
-4. **Construct the SDK client with a pinned version.** Official JS SDK is
-   `@notionhq/client` v5.12.0+ (latest 5.22.0, 2026-05-19); its default
-   `notionVersion` is `2025-09-03`, and it supports `2026-03-11` if you opt in.
-   The default and method names below are stable across the whole 5.x line.
+4. **Construct the SDK client with a pinned `Notion-Version`.** Official JS SDK
+   is `@notionhq/client` v5.12.0+ (latest 5.22.0, 2026-05-19); its default
+   `notionVersion` is the current major **`2025-09-03`**, and it supports the
+   latest **`2026-03-11`** if you opt in. The default and method names below are
+   stable across the whole 5.x line. Behavior differs across versions, so pin it
+   per client (or per request) — an unpinned client drifts when the default moves.
 
 ```ts
 import { Client } from "@notionhq/client"; // v5.12.0+ (latest 5.22.0)
@@ -66,9 +51,11 @@ const notion = new Client({
 
 ## The database → data source model (biggest gotcha)
 
-A database now holds a `data_sources` array; each data source has its **own
-schema**. One database can have several. You query and read schema against the
-*data source*, not the database.
+Post `2025-09-03` a database is a **container** of one or more data sources, not
+a queryable table: it holds a `data_sources` array and each data source has its
+**own schema**. Resolve the data source *before* you query — query and read
+schema against it, not against the database, or code that worked last year 404s
+silently.
 
 | You have… | Do this |
 |---|---|

package/skills/planetscale/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: planetscale
-description: "Use when operating PlanetScale serverless MySQL (Vitess) — setting up a database/branch and wiring the pscale CLI, shipping a schema change through branches and deploy requests, debugging a stuck/queued deploy or a cutover that won't finish, designing tables without foreign keys, or picking the serverless HTTP driver for an edge runtime. Triggers: 'schema change without downtime on PlanetScale', 'my migration is stuck in the deploy queue', 'the cutover hung', 'can I still revert 40 minutes after deploy', 'the 30-minute revert window', 'PlanetScale won't let me add a foreign key', 'relationMode prisma', 'MySQL connection times out on Vercel Edge', 'cambio de esquema sin downtime', 'no me deja usar foreign keys'. NOT raw MySQL query tuning, EXPLAIN, or index choice (that is postgresdb's MySQL-engine analogue / the mysql sibling), and NOT generic expand-contract migration theory (that is db-migrations)."
+description: "Use when operating PlanetScale (Vitess serverless MySQL) — branches and the `pscale` CLI, schema changes through deploy requests (Online DDL cutover, ~30-min revert window), tables without foreign keys, or the edge HTTP driver. NOT MySQL engine work like EXPLAIN or index choice (that is `mysql`), NOT generic migration theory (that is `db-migrations`)."
 tags: [planetscale, vitess, mysql, deploy-requests, serverless-db]
 recommends: [mysql, db-migrations, prisma-orm, drizzle-orm, github-actions, postgresdb]
 origin: risco
@@ -17,34 +17,15 @@ then **cuts over** with no table lock. Because Online DDL and sharding are the p
 gravity, you **design without foreign keys** (FKs are now an opt-in but unsharded-only feature). This
 skill owns that workflow — not MySQL the engine.
 
-## When to use / When NOT to use
+Heuristic for the boundary: **would this answer be identical on RDS MySQL? Then it is not this skill.**
 
-**When to use:**
-
-- Standing up a PlanetScale database, branch, or org and wiring the `pscale` CLI.
-- Shipping a schema change safely: dev branch → DDL → deploy request → diff → review → deploy → revert window.
-- A deploy request that is stuck/queued, a cutover that won't finish, or a lint error blocking deploy.
-- Designing relations when FKs are unavailable/discouraged: emulated relations, app-level integrity, ORM `relationMode`.
-- Choosing a connection path for edge/serverless (Cloudflare Workers, Vercel Edge, Lambda) where TCP MySQL is blocked.
-- Wiring deploy requests into CI (GitHub Actions) or a branch-per-PR preview database.
-
-**When NOT to use:**
-
-- A slow query, an `EXPLAIN` plan, an index decision, JSON columns, locking — that is MySQL-engine
-  work. The closest built sibling for engine-level relational guidance is `../postgresdb/SKILL.md`
-  (Postgres, but the engine-thinking transfers); pure MySQL tuning routes to the `mysql` sibling.
-  Heuristic: **would this answer be identical on RDS MySQL? Then it is not this skill.**
-- PostgreSQL engine/design — even PlanetScale's managed Postgres SQL semantics → `../postgresdb/SKILL.md`.
-  PlanetScale sells Postgres too, but this skill is strictly the **Vitess/MySQL branch+deploy-request** flow.
-- Engine-agnostic migration *theory* (expand-contract, backfill ordering) → the `db-migrations` sibling.
-  Here you get the concrete PlanetScale realization, not the theory.
-- Neon's Postgres copy-on-write branches → the `neon` sibling. Supabase's Postgres BaaS → `supabase`.
-- ORM client ergonomics (Prisma `updateMany`, Drizzle query builder) → `prisma-orm` / `../drizzle-orm/SKILL.md`.
-  This skill owns only the PlanetScale-specific knobs those ORMs expose (`relationMode`, serverless driver adapter).
-
-Deep dives: [deploy-requests](references/deploy-requests.md) (lifecycle states, queue/gating, lint
-errors, revert edge cases, declarative vs imperative) · [no-foreign-keys](references/no-foreign-keys.md)
-(emulated relations, ORM `relationMode`, the unsharded FK opt-in, Bad→Good schemas).
+| When the question is really about | Route to |
+| --- | --- |
+| A slow query, an `EXPLAIN` plan, an index decision, JSON columns, locking | `../mysql/SKILL.md` for MySQL-engine work; `../postgresdb/SKILL.md` when you want the transferable engine reasoning |
+| PostgreSQL engine/design — even PlanetScale's own managed Postgres SQL semantics | `../postgresdb/SKILL.md`. PlanetScale sells Postgres too; this skill is strictly the **Vitess/MySQL branch+deploy-request** flow |
+| Engine-agnostic migration *theory* (expand-contract, backfill ordering) | `../db-migrations/SKILL.md`. Here you get the concrete PlanetScale realization, not the theory |
+| Postgres copy-on-write branches | `../neon/SKILL.md`. Postgres BaaS → `../supabase/SKILL.md` |
+| ORM client ergonomics (Prisma `updateMany`, Drizzle query builder) | `../prisma-orm/SKILL.md` / `../drizzle-orm/SKILL.md`. This skill owns only the PlanetScale-specific knobs those ORMs expose (`relationMode`, serverless driver adapter) |
 
 ## Mental model
 
@@ -149,9 +130,14 @@ datasource db {
 ```
 
 With Drizzle, model the relation in app code (`relations()`), index the join column, and skip the
-`references()`-backed FK constraint at the DB layer. The opt-in unsharded FK is acceptable only when
-you are certain the table will never shard and you accept the Online DDL friction — see
-[no-foreign-keys](references/no-foreign-keys.md) for emulated cascades, ORM specifics, and the opt-in caveats.
+`references()`-backed FK constraint at the DB layer.
+
+| Will this table shard? | FK strategy | Notes |
+| --- | --- | --- |
+| Yes, or unsure | No DB FK — emulate in app/ORM | Default. Index the relation column; cascade in code. |
+| Never (small, bounded, unsharded) | Unsharded FK opt-in *is* acceptable | Accept Online DDL friction; document why it won't shard. |
+
+See [no-foreign-keys](references/no-foreign-keys.md) for emulated cascades, ORM specifics, and the opt-in caveats.
 
 ## Connecting
 
@@ -196,7 +182,7 @@ installs `pscale`, authenticates with a service token (`PLANETSCALE_SERVICE_TOKE
 
 For a **branch-per-PR preview database**, create a PlanetScale branch named after the PR head, run the
 app's migrations against it, and tear the branch down when the PR closes. The orchestration (matrix,
-secrets, cleanup-on-close) is generic CI — defer the Actions plumbing to the `github-actions` sibling
+secrets, cleanup-on-close) is generic CI — defer the Actions plumbing to `../github-actions/SKILL.md`
 and keep the PlanetScale verbs here.
 
 ## Anti-patterns
@@ -210,14 +196,3 @@ and keep the PlanetScale verbs here.
 | Treating revert as available forever | The window is **~30 min** and excludes dropped tables/cols and FK changes | Plan rollbacks as new forward deploys |
 | Deploying without reading `deploy-request diff` | You ship DDL you never saw; surprise table rewrites | Always run the diff before `deploy` |
 | Inventing a driver name (`@planetscale/serverless`, `planetscale-js`) | There is no such package; install fails | The package is exactly `@planetscale/database` |
-
-## Decision: FK strategy by sharding posture
-
-| Will this table shard? | FK strategy | Notes |
-| --- | --- | --- |
-| Yes, or unsure | No DB FK — emulate in app/ORM | Default. Index the relation column; cascade in code. |
-| Never (small, bounded, unsharded) | Unsharded FK opt-in *is* acceptable | Accept Online DDL friction; document why it won't shard. |
-
-When the question is really about reading a plan, picking an index, or query latency, that is engine
-work — route to the `mysql` sibling (or `../postgresdb/SKILL.md` for the transferable engine
-reasoning). This skill stops at the Vitess platform boundary.

package/skills/planetscale/references/no-foreign-keys.md

@@ -58,13 +58,13 @@ model Order {
 }
 ```
 
-ORM-client ergonomics beyond this knob belong to the `prisma-orm` sibling, not here.
+ORM-client ergonomics beyond this knob belong to `../../prisma-orm/SKILL.md`, not here.
 
 ## Drizzle: app-level relations
 
 Drizzle models relations in app code via `relations()` and queries them with the relational API. On
 PlanetScale you index the join column and skip the `references()`-backed DB constraint; the relation
-lives in code, not in the database. The query-builder side is the `../drizzle-orm/SKILL.md` sibling.
+lives in code, not in the database. The query-builder side is `../../drizzle-orm/SKILL.md`.
 
 ## The unsharded FK opt-in