@ericrisco/rsc 0.1.51 → 0.1.53

package/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.1.51",
+  "version": "0.1.53",
   "counts": {
     "skills": 258
   },
@@ -1889,7 +1889,7 @@
     },
     {
       "id": "gamedev-multiplayer",
-      "description": "Use when adding multiplayer, netcode, or replication to a game — syncing players/state across a network, online co-op or PvP, client-server vs peer-to-peer, server-authoritative design, client-side prediction + server reconciliation, snapshot interpolation, lag compensation, tick/netrate, and per-engine wiring: Godot 4.x MultiplayerSpawner/MultiplayerSynchronizer/@rpc/ENetMultiplayerPeer/set_multiplayer_authority, Unity Netcode for GameObjects (NetworkObject/NetworkBehaviour/NetworkVariable/[Rpc]/ServerRpc/ClientRpc), Unreal Actor replication (Replicated/ReplicatedUsing, Server/Client/NetMulticast RPCs, relevancy). Triggers: 'how do I sync players', 'client and server desync', 'players rubber-band or teleport', 'who has authority', 'laggy movement', 'cheater set their own health'. NOT single-player gameplay, AI, or input (route to engine skill godot/unity/unreal), and NOT matchmaking, dedicated-server hosting, or backend infra (route to deployment).",
+      "description": "Use when adding multiplayer or netcode to a game — client-server vs P2P, server authority and anti-cheat, state replication vs RPCs, prediction and reconciliation, lag compensation, plus Godot 4 / Unity NGO / Unreal wiring. NOT single-player gameplay (that is `godot`, `unity`, `unreal`), NOT matchmaking or server hosting (that is `deployment`).",
       "tags": [
         "multiplayer",
         "netcode",
@@ -1910,7 +1910,7 @@
     },
     {
       "id": "gamedev-pathing",
-      "description": "Use when implementing AI navigation or pathfinding in a game - moving enemies/NPCs/units toward goals, \\\"how do enemies navigate the level\\\", A*/Dijkstra/JPS/HPA* search, choosing grid vs waypoint-graph vs navmesh, baking a navmesh and tuning agent radius/height, off-mesh/nav links, dynamic obstacles and re-baking, steering (seek/flee/arrive/pursue/wander/path-following/flocking), local avoidance (RVO/ORCA, crowds), and flow fields for many agents to one goal. Per-engine: Godot 4.x (NavigationServer2D/3D, NavigationRegion, NavigationAgent, get_next_path_position), Unity (NavMeshAgent + NavMeshObstacle + AI Navigation baking), Unreal (RecastNavMesh + AIController + Behavior Trees/EQS). Triggers: \\\"my enemies get stuck\\\", \\\"units clump together\\\", \\\"navmesh not updating\\\", \\\"agentes se atascan\\\". NOT physics/rigidbody collision response or character-controller tuning (gamedev-physics), and NOT high-level enemy AI behaviour design like aggro/states/difficulty (game-design).",
+      "description": "Use when making NPCs, enemies, or units navigate a level — grid vs waypoint vs navmesh, A*/JPS, navmesh baking and agent radius, off-mesh links, steering, RVO crowd avoidance, and flow fields in Godot 4.x, Unity, Unreal. NOT collision response or character controllers (that is gamedev-physics), NOT aggro or difficulty design (that is game-design).",
       "tags": [
         "pathfinding",
         "navmesh",
@@ -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",
@@ -4175,7 +4175,7 @@
     },
     {
       "id": "security-scan",
-      "description": "Use when running automated security scanners over a repo or app and turning the raw output into a triaged, ranked, gate-able report: scan for vulnerabilities before shipping, audit dependencies/lockfiles for known CVEs, find secrets committed to the tree or git history, run SAST, or wire scanners into CI. Triggers: 'scan this repo for vulnerabilities', 'check my package-lock for CVEs', 'did anyone commit AWS keys', 'scan git history for leaked keys', 'my lockfile has a transitive CVE', 'is aquasecurity/trivy-action@latest safe', 'set up Semgrep/gitleaks to fail CI', 'escanea el repo en busca de vulnerabilidades', 'audita las dependencias', 'analitza les dependències'. NOT threat-modeling, OWASP design reasoning, or authoring the fix (that is secure-coding).",
+      "description": "Use when automated scanners drive a security sweep of a repo or app — SAST, dependency/lockfile CVEs, secrets in the tree or git history, IaC misconfig — and the raw output has to become one deduped, exploitability-ranked report CI can gate on. NOT threat-modeling, OWASP design reasoning, or hand-authoring the fix (that is `secure-coding`).",
       "tags": [
         "security",
         "sast",

package/package.json

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

package/skills/gamedev-multiplayer/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: gamedev-multiplayer
-description: "Use when adding multiplayer, netcode, or replication to a game — syncing players/state across a network, online co-op or PvP, client-server vs peer-to-peer, server-authoritative design, client-side prediction + server reconciliation, snapshot interpolation, lag compensation, tick/netrate, and per-engine wiring: Godot 4.x MultiplayerSpawner/MultiplayerSynchronizer/@rpc/ENetMultiplayerPeer/set_multiplayer_authority, Unity Netcode for GameObjects (NetworkObject/NetworkBehaviour/NetworkVariable/[Rpc]/ServerRpc/ClientRpc), Unreal Actor replication (Replicated/ReplicatedUsing, Server/Client/NetMulticast RPCs, relevancy). Triggers: 'how do I sync players', 'client and server desync', 'players rubber-band or teleport', 'who has authority', 'laggy movement', 'cheater set their own health'. NOT single-player gameplay, AI, or input (route to engine skill godot/unity/unreal), and NOT matchmaking, dedicated-server hosting, or backend infra (route to deployment)."
+description: "Use when adding multiplayer or netcode to a game — client-server vs P2P, server authority and anti-cheat, state replication vs RPCs, prediction and reconciliation, lag compensation, plus Godot 4 / Unity NGO / Unreal wiring. NOT single-player gameplay (that is `godot`, `unity`, `unreal`), NOT matchmaking or server hosting (that is `deployment`)."
 tags: [multiplayer, netcode, replication, networking, prediction, authority]
 recommends: [godot, unity, unreal, gamedev-physics]
 profiles: [full]
@@ -14,6 +14,16 @@ topology, put authority in the right place, replicate the right state, and hide
 opening the door to cheaters. This skill owns the *networking* decisions; the engine skills own
 the local gameplay those decisions sit on top of.
 
+Route elsewhere when the ask is not netcode:
+
+| The ask | Route to | Why not here |
+| --- | --- | --- |
+| Single-player movement, AI, input, animation, save files | [`godot`](../godot/SKILL.md) / [`unity`](../unity/SKILL.md) / [`unreal`](../unreal/SKILL.md) | The engine skill owns local gameplay; no network dimension. |
+| Physics determinism, collision, character controllers | [`gamedev-physics`](../gamedev-physics/SKILL.md) | Netcode *consumes* determinism; it does not own the physics fix. |
+| Matchmaking, lobby backend, dedicated-server hosting, relays, DB, game-server CI | [`deployment`](../deployment/SKILL.md) | Running the fleet, not designing the in-game net layer. |
+| Web realtime — chat, presence, a generic WebSocket app | [`webhooks`](../webhooks/SKILL.md) | Not a game world/simulation. |
+| General threat modeling, authz review | [`secure-coding`](../secure-coding/SKILL.md) | This skill keeps only the game-specific anti-cheat controls. |
+
 ## Version contract — read first
 
 Target the current APIs. **Never emit these deprecated / removed APIs:**
@@ -30,19 +40,6 @@ community UNet-like fork), say so; this skill targets first-party NGO. In NGO 2.
 `[ServerRpc]` / `[ClientRpc]` still compile (and enforce `…ServerRpc` / `…ClientRpc` method-name
 suffixes) — cover them but prefer the unified form on new code.
 
-## Fires on / When NOT
-
-**Fires on:** "how do I sync players", replication, netcode, RPCs, authority, online co-op or PvP,
-"client and server disagree", rubber-banding / teleporting players, prediction & reconciliation,
-lag compensation, tick rate / send rate, spawning networked objects, "the client can cheat".
-
-**When NOT (route away):**
-
-- Single-player movement, AI, input, animation, save files → the engine skill: `godot`, `unity`, `unreal`.
-- Physics determinism, collision, character controllers → `gamedev-physics` (netcode *consumes* it).
-- Matchmaking service, lobby backend, dedicated-server hosting/orchestration, relays, DB → `deployment`.
-- Web realtime (chat, presence, generic WebSocket app) that is not a game world → `webhooks` / a backend skill.
-
 ## Topologies & authority
 
 Pick the topology first; everything else follows from it.
@@ -61,7 +58,8 @@ requests), never results. **Never trust the client:** the client cannot set its
 score, currency, or hit results — it *asks*, the server *decides*, everyone else *observes*. A client
 that says "I moved to X / I did 40 damage / I have 999 gold" is either lagging or cheating; treat both
 the same. The one thing a client legitimately owns is its own input and, by convention, cosmetic-only
-state. See references/prediction-and-latency.md for how to keep this responsive.
+state. See **[references/prediction-and-latency.md](references/prediction-and-latency.md)** for how to
+keep this responsive.
 
 ## State replication vs RPCs
 
@@ -88,7 +86,7 @@ is the #1 cause of "it works for the host but not the client" bugs.
 ## The hard problems
 
 Latency (round-trip time, RTT) is the enemy; jitter and packet loss make it worse. Four techniques,
-covered in depth in **references/prediction-and-latency.md**:
+covered in depth in **[references/prediction-and-latency.md](references/prediction-and-latency.md)**:
 
 1. **Client-side prediction** — the owning client applies its own input *immediately* instead of waiting a
    full RTT for the server, so local movement feels instant.
@@ -140,7 +138,8 @@ func request_fire(target: Vector3) -> void:
 - `MultiplayerSynchronizer` streams a chosen property list (position, etc.) from the authority to peers;
   set its replication interval and visibility (`set_visibility_for(peer, bool)`) to scope bandwidth.
 - `MultiplayerSpawner` replicates instancing of scenes under a path so late peers get existing objects.
-- Details, prediction wiring, and the full player-scene pattern: **references/godot-high-level-multiplayer.md**.
+- Details, prediction wiring, and the full player-scene pattern:
+  **[references/godot-high-level-multiplayer.md](references/godot-high-level-multiplayer.md)**.
 
 ### Unity — Netcode for GameObjects
 
@@ -168,7 +167,8 @@ public class Player : NetworkBehaviour {
 - `NetworkVariable<T>(value, readPerm, writePerm)` — `NetworkVariableWritePermission.Server` (default) vs
   `.Owner`; subscribe via `OnValueChanged`. Use `NetworkTransform` for pos/rot sync.
 - Prefer the unified `[Rpc(SendTo.X)]`; legacy `[ServerRpc]`/`[ClientRpc]` still work but need the
-  method-name suffixes. Full patterns: **references/unity-and-unreal-netcode.md**.
+  method-name suffixes. Full patterns:
+  **[references/unity-and-unreal-netcode.md](references/unity-and-unreal-netcode.md)**.
 
 ### Unreal — Actor replication
 
@@ -196,7 +196,8 @@ void AMyPawn::GetLifetimeReplicatedProps(TArray<FLifetimeProperty>& Out) const {
 - **Relevancy** keeps bandwidth sane: `NetCullDistanceSquared`, `bAlwaysRelevant`, `IsNetRelevantFor`, and
   dormancy (`SetNetDormancy`) stop replicating actors a client can't perceive. Movement replicates via
   `CharacterMovementComponent`, which already does prediction+reconciliation for you.
-- RepNotify vs Multicast, GAS/Network Prediction notes: **references/unity-and-unreal-netcode.md**.
+- RepNotify vs Multicast, GAS/Network Prediction notes:
+  **[references/unity-and-unreal-netcode.md](references/unity-and-unreal-netcode.md)**.
 
 ## Security / anti-cheat basics
 
@@ -219,32 +220,18 @@ void AMyPawn::GetLifetimeReplicatedProps(TArray<FLifetimeProperty>& Out) const {
 - Always test **with simulated latency and packet loss**, not just on localhost — localhost hides every
   prediction/reconciliation bug. Test the client path, not only the host's.
 
-## Guardrails / gotchas
-
-- Localhost is a liar: 0 ms RTT masks the exact desync/rubber-band bugs your players will hit. Inject lag.
-- Don't RPC state you need to stay consistent — replicate it (an unreliable event drop is permanent).
-- Don't tie simulation to render FPS; fixed timestep on the sim, interpolate on the render.
-- The listen-server host is a client too — guard authority-only logic behind an `is_server`/`HasAuthority`
-  check or it double-executes on the host.
-- Wrong ownership = "works for host, breaks for client." Set authority/ownership explicitly on spawn.
-- Replicating everything, every tick, to everyone melts bandwidth — scope by relevancy/visibility and rate.
-
-## Related skills
-
-- **`godot` / `unity` / `unreal`** — the engine your game runs in; owns local gameplay, input, scenes, build.
-- **`gamedev-physics`** — determinism, collision, character controllers; netcode replicates its results and
-  needs its determinism for prediction/rollback.
-- **`deployment`** — dedicated-server hosting, matchmaking/lobby backend, relays, and CI for game servers.
-- **`secure-coding`** — general threat modeling; this skill keeps only the game-specific anti-cheat controls.
-
-## Checklist
-
-- [ ] Topology chosen (dedicated / listen / P2P) and the *same code* runs on server and listen host.
-- [ ] Server-authoritative: clients send intent only; server validates and owns all gameplay state.
-- [ ] Each networked value is either replicated (state/nouns) or an RPC (events/verbs) — not the wrong one.
-- [ ] Ownership/authority set explicitly per object; authority-only logic guarded on the host.
-- [ ] Owning-client movement predicted + reconciled; remote entities snapshot-interpolated.
-- [ ] Hitscan uses server-side lag compensation; simulation on a fixed tick, decoupled from render FPS.
-- [ ] Only need-to-know state replicated per client (relevancy/visibility scoped); RPCs rate-limited.
-- [ ] Tested with simulated latency + packet loss across multiple instances, exercising the client path.
-- [ ] No banned APIs (UNet/HLAPI, Godot 3.x `master`/`puppet`/`rset`, `Tick`-polled Unreal replication).
+## Anti-patterns
+
+| Anti-pattern | Why it bites | Do instead |
+| --- | --- | --- |
+| Writing net code before the topology is chosen | Authority and cost model change everything downstream | Pick dedicated / listen / P2P first, and make the *same code* run on server and listen host |
+| Trusting a client-reported result (health, position, score, hit) | That is the cheat surface, and lag looks identical to cheating | Clients send intent only; the server validates and owns all gameplay state |
+| RPCing state that must stay consistent | A dropped unreliable event desyncs that client permanently | Replicate nouns (state), RPC verbs (events) — replicated values self-correct |
+| Ownership/authority left implicit | The #1 cause of "works for the host, breaks for the client" | Set authority/ownership explicitly on spawn |
+| Forgetting the listen-server host is also a client | Authority-only logic double-executes on the host | Guard it behind `is_server()` / `HasAuthority()` |
+| Making the owning client wait a full RTT for its own input | Movement feels sluggish and unresponsive | Predict locally + reconcile; snapshot-interpolate remote entities |
+| Client-side hit detection for hitscan | Trivially spoofed, and unfair to the higher-ping shooter | Server-side lag compensation: rewind to the shooter's render time |
+| Tying simulation to render FPS | Sim diverges between machines at different frame rates | Fixed timestep on the sim, interpolate on the render |
+| Replicating everything, every tick, to everyone | Melts bandwidth and leaks wallhack fuel | Scope by relevancy/visibility and send rate; rate-limit RPCs |
+| Testing only on localhost | 0 ms RTT masks the exact desync/rubber-band bugs players will hit | Inject latency + packet loss across instances, exercising the client path |
+| Emitting UNet/HLAPI, Godot 3.x `master`/`puppet`/`rset`, or `Tick`-polled Unreal replication | Removed or legacy — it will not compile or will silently underperform | The current APIs in the version contract above |

package/skills/gamedev-pathing/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: gamedev-pathing
-description: "Use when implementing AI navigation or pathfinding in a game - moving enemies/NPCs/units toward goals, \"how do enemies navigate the level\", A*/Dijkstra/JPS/HPA* search, choosing grid vs waypoint-graph vs navmesh, baking a navmesh and tuning agent radius/height, off-mesh/nav links, dynamic obstacles and re-baking, steering (seek/flee/arrive/pursue/wander/path-following/flocking), local avoidance (RVO/ORCA, crowds), and flow fields for many agents to one goal. Per-engine: Godot 4.x (NavigationServer2D/3D, NavigationRegion, NavigationAgent, get_next_path_position), Unity (NavMeshAgent + NavMeshObstacle + AI Navigation baking), Unreal (RecastNavMesh + AIController + Behavior Trees/EQS). Triggers: \"my enemies get stuck\", \"units clump together\", \"navmesh not updating\", \"agentes se atascan\". NOT physics/rigidbody collision response or character-controller tuning (gamedev-physics), and NOT high-level enemy AI behaviour design like aggro/states/difficulty (game-design)."
+description: "Use when making NPCs, enemies, or units navigate a level — grid vs waypoint vs navmesh, A*/JPS, navmesh baking and agent radius, off-mesh links, steering, RVO crowd avoidance, and flow fields in Godot 4.x, Unity, Unreal. NOT collision response or character controllers (that is gamedev-physics), NOT aggro or difficulty design (that is game-design)."
 tags: [pathfinding, navmesh, navigation, steering, a-star]
 recommends: [godot, unity, unreal, gamedev-physics]
 profiles: [full]
@@ -102,7 +102,8 @@ Combine either as a **weighted sum** (simple) or **priority/arbitration** (avoid
 **Local avoidance (RVO / ORCA):** each agent picks a velocity that is collision-free assuming neighbours
 share the burden (*reciprocal* — hence no oscillating "dance"). This is avoidance, **not** collision
 *response*: it changes intended velocity *before* moving; the physics/collision solver is a separate,
-last-resort backstop (→ `gamedev-physics`). For dense crowds use the engine's crowd/avoidance system.
+last-resort backstop (→ [`gamedev-physics`](../gamedev-physics/SKILL.md)). For dense crowds use the
+engine's crowd/avoidance system.
 
 **Flow fields** — for **many agents → one (or few) goals** (RTS swarm, tower-defense creeps): run one
 **Dijkstra from the goal** over the grid to build a cost/integration field, derive a per-cell direction
@@ -182,30 +183,26 @@ AICon->MoveToActor(TargetActor, /*AcceptanceRadius*/ 50.f);   // or MoveToLocati
 4. Costs/holes: **`NavModifierVolume`** + `NavArea` classes. Off-mesh: **`NavLinkProxy`**. Crowd
    avoidance: enable the **Detour Crowd** manager (or `DetourCrowdAIController`) for RVO on many agents.
 
-> High-level BT *design* (states, aggro, difficulty) is `game-design`; this skill wires the BT's
+> High-level BT *design* (states, aggro, difficulty) is [`game-design`](../game-design/SKILL.md); this skill wires the BT's
 > movement/EQS tasks to navigation, not the decision tree's semantics.
 
-## Guardrails / gotchas
+## Anti-patterns
 
-- **Agent radius mismatch** is the top "stuck in doorways / clipping walls" cause — bake with the real radius.
-- Bake covers **static** geometry; runtime-spawned meshes need a rebake, a carving obstacle, or a nav link.
-- Path returns empty when start/end are **off the navmesh** or in disconnected islands — snap to nearest poly and check reachability first.
-- Avoidance (RVO) ≠ collision (physics). Agents can still overlap under pressure; that is expected, not a physics bug.
-- Off-mesh links are **directional and manual** — a jump-down link does not imply a jump-up link.
-- Smooth grid paths (funnel / string-pull) or agents walk visible zig-zag staircases.
-
-## Anti-patterns / rationalizations → STOP
-
-| Rationalization | Reality / do instead |
+| Anti-pattern | Do instead |
 | --- | --- |
-| "Just A* every frame, it's fine" | Melts CPU at scale; path on goal-change, steer between frames. |
-| "One navmesh bake works for every unit" | Radius/height differ; bake per agent size or use agent-type profiles. |
-| "Agents clip through each other — physics bug" | Missing **local avoidance**; enable RVO/crowd, that's the navigation layer. |
-| "Navmesh doesn't see my spawned wall" | Static bake; set Dynamic/rebake, or add a carving obstacle/nav link. |
-| "I'll grid-search my own A* in Unity/Unreal" | Reinvents the built-in navmesh; use `NavMeshAgent` / `AAIController::MoveTo`. |
-| "500 zombies each run A* to the player" | That's a **flow field**: one Dijkstra from the goal, agents sample cells. |
-| "Set `agent.destination` and read the path same frame" | Path is async (`pathPending`); gate on it before trusting `remainingDistance`. |
-| "Bigger heuristic = smarter" | Over-estimating `h` breaks A* optimality; keep it admissible (or weight it *knowingly*). |
+| Running a full A* every frame | Path on goal-change (or throttled) and steer between frames — per-frame search melts CPU at scale. |
+| One navmesh bake shared by every unit | Radius/height differ; bake per agent size or use agent-type profiles. |
+| Baking with a placeholder agent radius | Bake with the real radius — mismatch is the top "stuck in doorways / clipping walls" cause. |
+| Treating agents that clip through each other as a physics bug | Missing **local avoidance**; enable RVO/crowd — that is the navigation layer. |
+| Expecting RVO to prevent every overlap | Avoidance ≠ collision. Agents can still overlap under pressure; that is expected, not a physics bug. |
+| Expecting a **static** bake to see runtime-spawned geometry | Set Dynamic runtime generation / rebake, or add a carving obstacle or nav link. |
+| Hand-rolling your own grid A* in Unity/Unreal | Reinvents the built-in navmesh; use `NavMeshAgent` / `AAIController::MoveTo`. |
+| 500 zombies each running A* to the player | That's a **flow field**: one Dijkstra from the goal, agents sample cells. |
+| Setting `agent.destination` and reading the path the same frame | Path is async (`pathPending`); gate on it before trusting `remainingDistance`. |
+| Inflating `h` because a bigger heuristic seems smarter | Over-estimating `h` breaks A* optimality; keep it admissible (or weight it *knowingly*). |
+| Trusting a path query that came back empty | Start/end are **off the navmesh** or in disconnected islands — snap to the nearest poly and check reachability first. |
+| Assuming an off-mesh link works both ways | Links are **directional and manual** — a jump-down link does not imply a jump-up link. |
+| Feeding raw grid paths to the mover | Smooth them (funnel / string-pull) or agents walk visible zig-zag staircases. |
 
 ## Related skills
 
@@ -213,7 +210,7 @@ AICon->MoveToActor(TargetActor, /*AcceptanceRadius*/ 50.f);   // or MoveToLocati
 - [`unity`](../unity/SKILL.md) — Unity/C# project setup; here for the NavMesh + AI Navigation package details.
 - [`unreal`](../unreal/SKILL.md) — UE5/Blueprint/C++; here for RecastNavMesh + AIController/BT/EQS wiring.
 - [`gamedev-physics`](../gamedev-physics/SKILL.md) — collision *response*, rigidbodies, character controllers; steering decides intended velocity, physics resolves the contact.
-- `game-design` — high-level enemy behaviour, aggro, encounter/difficulty design (what the AI *decides*, not how it *moves*).
+- [`game-design`](../game-design/SKILL.md) — high-level enemy behaviour, aggro, encounter/difficulty design (what the AI *decides*, not how it *moves*).
 
 ## Checklist
 
@@ -234,9 +231,3 @@ the project's navigation decisions in `02-DOCS/wiki/stack/gamedev-pathing.md` (i
 `02-DOCS/wiki/index.md`): engine + version, chosen representation, bake settings (agent sizes, cell
 size), avoidance/crowd choice, custom links/areas. Read it first on every use; bump its `Updated` date
 when a convention changes. No `02-DOCS/` layer? Skip silently — conventions are *recorded, not gated*.
-
-## See Also — local references (read when)
-
-- `references/search-algorithms.md` — representations, A*/Dijkstra/JPS/HPA* pseudocode, heuristics & admissibility, tie-breaking, any-angle, funnel smoothing.
-- `references/navmesh-workflow.md` — bake-parameter table, areas/costs, off-mesh links, obstacles vs carving vs partial rebake, per-engine baking, debugging.
-- `references/steering-and-avoidance.md` — steering primitives, path following, boids weights, RVO/ORCA intuition, crowds, flow-field construction.

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.