@dsalazardev/ai-hub-cli 0.0.0-stage → 0.2.0

package/skills/shared/laravel/references/queues-and-scheduling.md

@@ -0,0 +1,153 @@
+# Queues & scheduling (deep dive)
+
+Offloaded depth from SKILL.md §Queues & scheduling. The body covers `ShouldQueue`, `$tries`,
+`backoff()`, batches with `allowFailures()`, and the database-vs-Redis driver decision. This
+file covers the operational layer: Horizon, the failure pipeline, and worker deployment.
+
+## Driver selection (expanded)
+
+| Driver | Infra | Choose when |
+|---|---|---|
+| `sync` | none (runs inline) | local debugging only; **the default in tests** — jobs run inline |
+| `database` | a `jobs` + `job_batches` + `failed_jobs` table | low/medium volume, no Redis, simplest ops |
+| `redis` | Redis | high throughput, low latency; pair with Horizon |
+| `sqs` / others | cloud | you already run on that provider's queue |
+
+Create the tables for the database driver:
+
+```bash
+php artisan make:queue-table
+php artisan make:queue-batches-table
+php artisan migrate
+```
+
+## Horizon (Redis only)
+
+Horizon is the first-party dashboard + supervisor for Redis queues — throughput, runtime,
+retries, failed jobs, and tag-based metrics, configured in code (not a separate UI to wire).
+
+```bash
+composer require laravel/horizon
+php artisan horizon:install
+php artisan horizon            # runs the supervised workers (instead of queue:work)
+```
+
+```php
+// config/horizon.php — environment-specific worker pools.
+'environments' => [
+    'production' => [
+        'supervisor-1' => [
+            'connection' => 'redis',
+            'queue'      => ['high', 'default'],
+            'balance'    => 'auto',     // scale processes to load
+            'maxProcesses' => 10,
+            'tries'      => 3,
+            'timeout'    => 120,
+        ],
+    ],
+],
+```
+
+In production run `php artisan horizon` under a process supervisor (below). Deploys call
+`php artisan horizon:terminate` so workers gracefully finish the current job and restart on
+the new code.
+
+## Retry / backoff / timeout matrix
+
+| Knob | Where | Meaning |
+|---|---|---|
+| `$tries` | job property | max attempts before the job is marked failed |
+| `$maxExceptions` | job property | fail after N exceptions even if `$tries` not hit |
+| `backoff()` | job method (array) | seconds to wait between attempts (`[10, 60, 300]`) |
+| `$timeout` | job property | seconds the worker allows before killing the job |
+| `retryUntil()` | job method | a `DateTime` after which it stops retrying (overrides `$tries`) |
+| `$backoff` on worker | `queue:work --backoff=` | default wait when a job has no own backoff |
+
+Set `$timeout` **less** than the queue connection's `retry_after` (config/queue.php) — if a
+job runs longer than `retry_after`, the queue releases it to a second worker and you get
+duplicate processing.
+
+## The failure pipeline
+
+A job that exhausts `$tries` lands in `failed_jobs`. Inspect and replay:
+
+```bash
+php artisan queue:failed              # list failed jobs with their UUIDs
+php artisan queue:retry <uuid>        # requeue one
+php artisan queue:retry all           # requeue everything
+php artisan queue:forget <uuid>       # drop one
+php artisan queue:flush               # clear the failed table
+```
+
+Add a `failed()` method to the job for compensating actions (notify, refund, mark record):
+
+```php
+public function failed(\Throwable $e): void {
+    $this->order->update(['status' => 'failed']);
+    Notification::route('slack', config('alerts.ops'))->notify(new JobFailed($e));
+}
+```
+
+For batches, `catch()` fires on the first failed job and `finally()` always runs:
+
+```php
+Bus::batch($jobs)
+    ->allowFailures()
+    ->catch(fn (Batch $b, \Throwable $e) => Log::error('batch member failed', ['e' => $e]))
+    ->finally(fn (Batch $b) => Log::info("batch {$b->id} done, failures: {$b->failedJobs}"))
+    ->dispatch();
+```
+
+## Worker deployment
+
+Run workers as a long-lived supervised process — **never** `queue:work` in a bare shell in
+prod (it dies with the SSH session and won't restart).
+
+```ini
+; /etc/supervisor/conf.d/laravel-worker.conf
+[program:laravel-worker]
+process_name=%(program_name)s_%(process_num)02d
+command=php /var/www/app/artisan queue:work redis --sleep=3 --tries=3 --max-time=3600
+autostart=true
+autorestart=true
+numprocs=4
+stopwaitsecs=3600   ; let in-flight jobs finish on stop (must exceed longest job)
+```
+
+Useful `queue:work` flags:
+
+| Flag | Effect |
+|---|---|
+| `--max-time=3600` | exit after an hour so a fresh worker reclaims leaked memory |
+| `--max-jobs=1000` | exit after N jobs (same memory hygiene) |
+| `--tries=3` | default attempts (job's own `$tries` wins) |
+| `--queue=high,default` | priority order — drain `high` first |
+| `--once` | process a single job then exit (handy in tests/scripts) |
+
+## Graceful restarts on deploy
+
+```bash
+php artisan queue:restart       # signals workers to finish the current job then exit
+# (supervisor / horizon:terminate then restarts them on the new code)
+```
+
+Workers hold the **old** code in memory until restarted — forget `queue:restart` in your
+deploy script and you ship a bug fix that never reaches the queue.
+
+## Scheduling
+
+The scheduler lives in `routes/console.php` (L11/12 — no `app/Console/Kernel.php`). One
+system cron entry drives it:
+
+```cron
+* * * * * cd /var/www/app && php artisan schedule:run >> /dev/null 2>&1
+```
+
+```php
+// routes/console.php
+Schedule::command('orders:reconcile')->dailyAt('02:00')->onOneServer()->withoutOverlapping();
+Schedule::job(new PruneStaleCarts)->hourly();
+```
+
+`->onOneServer()` (needs a shared cache lock) stops a multi-server fleet running the same
+task N times; `->withoutOverlapping()` skips a run if the previous one is still going.

package/skills/shared/laravel/scripts/verify.sh

@@ -0,0 +1,128 @@
+#!/usr/bin/env bash
+#
+# verify.sh - local quality gate for a Laravel (11/12) project.
+#
+# Usage:
+#   cd <your-laravel-project-root>   # the directory containing composer.json + artisan
+#   ./verify.sh
+#
+# Runs (each only if applicable): composer validate, a framework-version sanity check,
+# Pint style in read-only --test mode, the test runner (Pest or `php artisan test`), and a
+# grep guard against `protected $guarded = []` under app/Models.
+# Read-only: never mutates source, never runs a formatter/migration in write mode.
+#
+# Degrades gracefully: if there is no Laravel project (no composer.json, or composer.json
+# without laravel/framework) or no vendor/ dir, it prints a skip notice and EXITS 0 so it
+# never blocks a non-Laravel repo. Portable to stock macOS bash 3.2.
+
+set -euo pipefail
+
+if [ -t 1 ]; then
+  YELLOW=$'\033[33m'; RED=$'\033[31m'; GREEN=$'\033[32m'; RESET=$'\033[0m'
+else
+  YELLOW=''; RED=''; GREEN=''; RESET=''
+fi
+
+failed=0
+
+have() { command -v "$1" >/dev/null 2>&1; }
+warn() { printf '%s[skip]%s %s\n' "$YELLOW" "$RESET" "$*"; }
+fail() { printf '%s[fail]%s %s\n' "$RED" "$RESET" "$*"; failed=1; }
+ok()   { printf '%s[ ok ]%s %s\n' "$GREEN" "$RESET" "$*"; }
+info() { printf -- '----- %s\n' "$*"; }
+
+# Resolve a binary either as a project-local vendor/bin script or a global on PATH.
+binof() {
+  if [ -x "vendor/bin/$1" ]; then printf 'vendor/bin/%s' "$1"; return 0; fi
+  if have "$1"; then printf '%s' "$1"; return 0; fi
+  return 1
+}
+
+# --- Applicability gate: bail out cleanly when this is not a Laravel project. ---
+if [ ! -f composer.json ]; then
+  warn "no composer.json in $(pwd) - not a Laravel project, nothing to verify."
+  exit 0
+fi
+if ! grep -q 'laravel/framework' composer.json 2>/dev/null; then
+  warn "composer.json has no laravel/framework dependency - skipping Laravel checks."
+  exit 0
+fi
+if [ ! -d vendor ]; then
+  warn "no vendor/ dir - run 'composer install' first. Skipping (exit 0)."
+  exit 0
+fi
+
+# 1. composer validate - the manifest must be well-formed.
+info "composer validate"
+if have composer; then
+  if composer validate --strict --no-check-publish >/dev/null 2>&1; then
+    ok "composer.json valid"
+  elif composer validate --no-check-publish >/dev/null 2>&1; then
+    warn "composer.json valid but not strict-clean (lock drift / metadata) - run: composer validate --strict"
+  else
+    fail "composer validate reported errors (run: composer validate)"
+  fi
+else
+  warn "composer not found (https://getcomposer.org)"
+fi
+
+# 2. Framework version sanity. Prefer artisan; fall back to composer.lock.
+info "framework version"
+if [ -f artisan ] && have php; then
+  ver="$(php artisan --version 2>/dev/null || true)"
+  if [ -n "$ver" ]; then ok "$ver"; else warn "could not read 'php artisan --version'"; fi
+elif [ -f composer.lock ]; then
+  lver="$(grep -A2 '"name": "laravel/framework"' composer.lock 2>/dev/null | grep '"version"' | head -n1 || true)"
+  if [ -n "$lver" ]; then ok "composer.lock laravel/framework:$lver"; else warn "version not found in composer.lock"; fi
+else
+  warn "no artisan / composer.lock - cannot determine framework version"
+fi
+
+# 3. Mass-assignment guard: flag `protected $guarded = []` under app/Models.
+info "mass-assignment guard (no \$guarded = [])"
+if [ -d app/Models ]; then
+  # Match an empty-array $guarded with any inner whitespace; ignore commented lines best-effort.
+  if grep -REn 'protected[[:space:]]+\$guarded[[:space:]]*=[[:space:]]*\[[[:space:]]*\]' app/Models 2>/dev/null \
+       | grep -v '^[^:]*:[0-9]*:[[:space:]]*//' >/dev/null; then
+    grep -REn 'protected[[:space:]]+\$guarded[[:space:]]*=[[:space:]]*\[[[:space:]]*\]' app/Models 2>/dev/null \
+      | grep -v '^[^:]*:[0-9]*:[[:space:]]*//' || true
+    fail "found 'protected \$guarded = []' (mass-assignment footgun) - use an explicit \$fillable allowlist"
+  else
+    ok "no open \$guarded found in app/Models"
+  fi
+else
+  warn "no app/Models dir - skipping mass-assignment guard"
+fi
+
+# 4. Style: Pint in read-only --test mode (never fixes).
+info "style (Pint)"
+if pint_bin="$(binof pint)"; then
+  if $pint_bin --test >/dev/null 2>&1; then
+    ok "pint clean"
+  else
+    fail "pint reports style issues (run: $pint_bin)"
+  fi
+else
+  warn "no pint binary (composer require --dev laravel/pint) - skipping style"
+fi
+
+# 5. Tests: Pest preferred, else `php artisan test`.
+info "tests (Pest / artisan test)"
+if [ -f phpunit.xml ] || [ -f phpunit.xml.dist ] || [ -d tests ]; then
+  if pest_bin="$(binof pest)"; then
+    if $pest_bin >/dev/null 2>&1; then ok "pest green"; else fail "pest failed (run: $pest_bin)"; fi
+  elif [ -f artisan ] && have php; then
+    if php artisan test >/dev/null 2>&1; then ok "artisan test green"; else fail "artisan test failed (run: php artisan test)"; fi
+  else
+    warn "tests present but no runner found (composer require --dev pestphp/pest)"
+  fi
+else
+  warn "no phpunit.xml / tests dir - skipping tests"
+fi
+
+echo
+if [ "$failed" -ne 0 ]; then
+  printf '%sFAIL:%s one or more checks failed.\n' "$RED" "$RESET"
+  exit 1
+fi
+printf '%sPASS:%s all checks passed.\n' "$GREEN" "$RESET"

package/skills/shared/level-design/SKILL.md

@@ -0,0 +1,143 @@
+---
+name: level-design
+description: "Use when designing a game level's space — blockout/greybox layout, pacing that drags or spikes, guiding lost players without waypoints, encounter and arena progression, or secret placement. NOT mechanics or economy (that is `game-design`), NOT story beats (that is `game-storytelling`), NOT engine tooling like nav meshes or lightmaps (that is `godot`/`unity`/`unreal`)."
+tags: [level-design, blockout, pacing, encounter, playtest]
+recommends: [game-design, godot, unity, unreal]
+profiles: [full]
+origin: ai-hub
+---
+
+# Level design — space that plays before it's pretty
+
+*Shape the space, the rhythm, and the encounters so the player always knows where to go, never gets bored, and feels smart for exploring. Prove it in grey boxes; add art last.*
+
+This skill owns the **craft of physical space and its play**: how a level is laid out, how it reads, how its intensity rises and falls, how encounters teach, and where reward hides. It is **engine-agnostic** — every technique here is validated in a blockout, then handed to an engine skill for the actual tooling.
+
+## The pipeline: blockout -> greybox -> playtest -> art (never art-first)
+
+**Lock the player's metrics first** — height, jump, reach, cover, door/corridor widths — and build all geometry as multiples of them. Guessing widths breaks traversal after the space is full of dependent geometry, which is why this comes before the first box. → `references/blockout-to-art.md`
+
+| Stage | You build | You answer | Gate to next |
+|---|---|---|---|
+| **Blockout** | Primitive geometry only (boxes/planes at true metrics). No materials, no props. | Does the space flow? Are timings/distances right? Can I find my way? | Layout & traversal feel right. |
+| **Greybox** | Blockout + temp neutral materials, placeholder lighting, stand-in enemies/interactables. | Does it *read*? Does the fight/encounter work? Is pacing right? | Encounters and readability hold up in playtest. |
+| **Playtest** | Nothing — you watch fresh players. | Where do they hesitate, get lost, die, skip? | Fixes are cheap because it's still grey. |
+| **Art pass** | Meshes, materials, VFX, final lighting, audio — *serving* the proven layout. | Does art reinforce the guidance the greybox already established? | Ship. |
+
+Iterate blockout↔playtest many times before art: changing a grey box is minutes, changing a finished art set-piece is days — so never model or texture a space you have not already proven fun. Full stage detail, the metrics block, and the art-pass handoff checklist → `references/blockout-to-art.md`.
+
+## Spatial composition — leading the eye
+
+- **Sightlines are your steering wheel.** Control what's visible from each point: frame the objective in a doorway/arch, block distracting views, open a reveal at the moment of a decision.
+- **Landmarks (the "weenie").** One large, distinct, distant silhouette per area that the player orients toward (tower, spire, mountain) — Disney's term for the visual magnet that pulls you forward. Self-locating beats a minimap.
+- **Lead the eye** with converging lines (rails, beams), framing (foreground arches), contrast (a bright end to a dark corridor), and motion. The eye goes to the brightest, highest-contrast, most-different thing — put that on the path you want taken.
+- **Silhouette readability.** Enemies, interactables, and hazards must read by shape alone at a glance. Two things sharing a silhouette is an unintended trap.
+- **Golden path vs exploration.** The **critical path** is the always-legible guaranteed route to the objective; **exploration** is optional branches and loops off it. The player must always know where to go and never how it ends. Prefer loops that return the player forward (avoid dead-end backtracking); breadcrumb side routes with a visible reward.
+
+Framing, contrast, and layout topologies (loops, hubs, gates) → `references/guidance-and-readability.md`.
+
+## Pacing & rhythm — tension and release
+
+Design the **intensity graph** for the whole level, not room by room. Intensity must rise and fall — sustained peak is fatigue, sustained calm is boredom. A good level is a sawtooth trending upward: each peak (combat, platforming gauntlet, chase) followed by a valley — a **safe room / breather** with no threat, low stimulus, often a save/restock.
+
+- **Space encounters in time and distance, and *vary* both** — three identical-length fights back to back feel like one long slog.
+- **Breathers earn the next peak.** The calm between (Halo's cadence is often described as "thirty seconds of fun" on repeat) is what makes the fun read as fun. Use it to let adrenaline drop, reward observation, and telegraph the next escalation.
+- **Difficulty within the level** trends up but resets at checkpoints — re-enter competent, then ramp. End on the hardest, most spectacular test, not a whimper.
+- **Contrast the modes** (fast↔slow, loud↔quiet, open↔tight, combat↔traversal↔puzzle). Monotony of *any* mode reads as boredom even if each moment is individually good.
+
+Intensity-graph template, breather patterns, and difficulty-curve worked example → `references/pacing-and-encounters.md`.
+
+## Encounter design — introduce, develop, twist, combine
+
+Teach through space, not text: the four-beat progression (the pattern behind Portal, Half-Life 2, and Mario level craft) introduces a threat where it is safe to learn, before it can kill.
+
+1. **Introduce** — meet the new element somewhere it *can't* hurt you. A single turret across a safe gap; one platform of the new hazard. Learn it risk-free.
+2. **Develop** — use it for real, low stakes. The turret now guards a corridor you must cross.
+3. **Twist** — recontextualize it. Two turrets flanking; the turret is *behind* glass; you must use the turret against enemies. The rule bends.
+4. **Combine** — the mastery test: the new element plus everything learned earlier, at full intensity.
+
+Design rules for the **arena** (the shape a fight happens in):
+
+- **Match sightline length to weapon/threat range** — long lanes favor ranged, tight rooms favor melee/shotgun. The geometry *is* the difficulty knob.
+- **Cover rhythm, flanks, verticality.** Space cover so the player advances in beats; give at least one flank so a fight isn't a static peek-war; use height for pressure and reward (the Doom-2016 arena: multi-tier, resources placed to pull the player *through* the space, not hunker).
+- **Chokepoints need release valves** — pair a choke with an exit or a way to break the standoff, or the fight stalls.
+- **An encounter = enemy composition × space × objective × resources.** Change any one for a "new" encounter without new assets.
+
+Encounter template, arena patterns, and a full introduce→develop→twist→combine example → `references/pacing-and-encounters.md`.
+
+## Guidance & readability — direct without hand-holding
+
+Guide with the environment so you never need a floating arrow. When a player is lost, that is a readability bug in the level, not player error:
+
+- **Light leads.** Players move toward light (the moth effect) and higher value-contrast. Light the path, objective, and exit; keep dead-ends dim. Placeholder lighting is a greybox *design* tool, not a final-art afterthought.
+- **Reserve one accent color for "you can interact / go here"** (Mirror's Edge runner red, Dishonored's usable glint) and **never** use it decoratively. Consistency is the whole point; break it once and you've lied to the player.
+- **Composition** — framing, leading lines, and negative space point the eye like a photographer's shot. The critical path should be the most-framed, highest-contrast route from any decision point.
+- **Affordances & signifiers** (Norman/Gibson): a ledge that looks grabbable must be grabbable. Establish the visual language early and hold it — if a trim means "climb here", it appears *only* where you can climb. Inconsistent affordances are the #1 cause of "I didn't know I could do that."
+- **Deny wrong turns visually** (subtle dead-ends, unlit gaps, a "not-a-path" material) rather than with invisible collision.
+
+Full catalog — lighting/color/composition, the affordance language, the "critical-path readability" self-test → `references/guidance-and-readability.md`.
+
+## Metrics & playtesting — where players get lost and stuck
+
+You cannot see your own level fresh, so every claim ("this is obvious", "the fight is fun") is a hypothesis until a fresh player validates it. **Observe, don't coach:**
+
+- **Watch a first-timer play, silent.** Note every hesitation (readability gap), wrong turn (navigation gap), repeated death (telegraph/difficulty gap), and skipped content (reward-placement gap). Do **not** answer "where do I go?" — that question *is* the finding.
+- **Traversal telemetry** turns anecdote into pattern: **position heatmaps** (cold zones players never enter = wasted level), **death heatmaps** (clusters = unfair/unreadable threats), **path traces** (golden path or lost?), **dwell time** at forks (long dwell = unclear guidance), and **look/aim heatmaps** (did they even see the landmark?).
+- **Read the map:** a cold region means the space doesn't pull the player there — re-light, add a landmark/reward, or cut it. A death cluster means fix the telegraph or arena, not the player. A branch nobody takes needs a visible reward at its mouth.
+
+Playtest protocol, question scripts, and turning heatmaps into fixes → `references/guidance-and-readability.md`.
+
+## Reward & secret placement, risk vs reward
+
+- **Reward the wandering eye.** Put secrets where a *curious* player naturally looks — behind the waterfall, up the ledge you already lit and framed, down the branch you breadcrumbed. Reward observation, not pixel-hunting; a secret nobody can reasonably find just frustrates.
+- **Breadcrumb the secret** with a glint, an out-of-place object, a suspicious seam, an "impossible" bit of geometry visible from the path. The player should feel *clever* — which means the game showed them the thread first.
+- **Risk vs reward.** Gate the best optional reward behind the biggest optional risk or detour. Keep the *critical path* rewarding on its own so risk-averse players aren't punished; put the *extra* behind the extra effort, both visible before committing.
+- **Never hide mandatory progression like a secret** — a required key/door disguised as optional is a stuck-player generator. Secrets are optional by definition.
+- **Vary reward types**: power/upgrade, resources, lore/collectible, a **shortcut unlock** (best long-term — reshapes the level), and pure spectacle.
+
+Reward taxonomy, secret-signposting, and risk/reward tuning → `references/guidance-and-readability.md`.
+
+## Anti-patterns
+
+| Anti-pattern | Do instead |
+|---|---|
+| Making it look good first, then tuning the layout. | Art-first burns days reworking assets when the layout changes. Blockout, playtest, *then* art. |
+| Trusting that it's "obvious where to go". | Obvious to *you*, the author. Fresh players get lost. Watch one before you believe it. |
+| Patching confusion with a waypoint arrow or big text prompt. | That's a patch over a readability failure. Fix it with light, framing, and a landmark first. |
+| Keeping the whole level intense because intensity is exciting. | Sustained peak = fatigue and it all flattens into noise. Add breathers so the peaks read. |
+| Reusing the space by sending the player back the way they came. | Repeated dead-end backtracking reads as padding. Use loops that return the player forward. |
+| Dropping a new mechanic in and expecting players to figure it out. | Not while it's killing them. Introduce it where it's safe, then develop/twist/combine. |
+| Yellow paint everywhere so they see the ledges. | Only if yellow means *exactly* climbable and appears nowhere else. Inconsistent affordances lie. |
+| Hiding a secret so well nobody finds it. | A secret with no breadcrumb is just frustration. Show the thread; reward the curious eye. |
+| Eyeballing gap, cover, and door widths because they feel about right. | Guessing metrics breaks traversal later. Set the metrics block first; build to multiples. |
+
+## Related skills
+
+- `game-design` — the systemic layer: mechanics, verbs, economy, progression, difficulty *systems*. Level design exercises those verbs in space; if the request is about the rules themselves, route there.
+- `game-storytelling` — narrative, quests, dialogue, and the meaning of environmental beats. Level design places the beat; storytelling authors it.
+- `godot` / `unity` / `unreal` — the engine tooling that *implements* a proven layout: nav meshes, occlusion, terrain/tilemap editors, lightmap/GI bakes, streaming, collision. Hand off here after the blockout plays well.
+- `harness` — the `02-DOCS` Karpathy-wiki this skill records level conventions into.
+
+## Checklist
+
+- [ ] Player metrics block locked (height, jump, reach, cover, door/corridor widths) before geometry.
+- [ ] Layout proven in blockout/greybox — never modeled or textured before it plays well.
+- [ ] Critical path is legible from every decision point; a fresh player can find the objective without being told.
+- [ ] One dominant landmark orients each area; light and framing lead the eye along the intended path.
+- [ ] Intensity graph is a sawtooth (peaks + breathers), not a flat line; encounters vary in length and spacing.
+- [ ] At least one safe room / breather follows each major peak.
+- [ ] Every new mechanic/threat is introduced safely, then developed, twisted, and combined.
+- [ ] Arenas match sightline length to threat range and offer a flank/verticality option, not a static peek-war.
+- [ ] One reserved accent color for interactables/path, used consistently and never decoratively; affordances hold everywhere.
+- [ ] Played by a fresh, uncoached tester (and/or telemetry): hesitations/lost/deaths/skips logged, no dead cold-zones, no unfair death clusters, no ignored branches.
+- [ ] Secrets are breadcrumbed and reward observation; no mandatory progression hidden as a secret; best optional reward sits behind the biggest optional risk.
+
+## Project grounding (02-DOCS + CLAUDE.md)
+
+When this skill runs in a project with a `02-DOCS/` layer (the [`harness`](../harness/SKILL.md) Karpathy wiki), record the level-design conventions there and index them from the root `CLAUDE.md`, so the next agent inherits them instead of re-deriving:
+
+1. **Find the article** `02-DOCS/wiki/stack/level-design.md`, indexed in `02-DOCS/wiki/index.md` (the Knowledge map).
+2. **If missing or stale**, create/update it with the project's real conventions — the metrics block, the reserved interact-color, the pacing/breather cadence, the encounter-teaching pattern, and any per-level intensity graphs — then index it.
+3. **Read it first on every use** and stay consistent; when a convention changes, update the article (bump its `Updated` date) in the same change.
+
+No `02-DOCS/` layer? Skip silently (optionally suggest `harness`). Conventions are *recorded, not gated* — never block the design work on this.

package/skills/shared/level-design/evals/README.md

@@ -0,0 +1,35 @@
+# Eval harness — level-design
+
+These evals assert two things about the `level-design` skill. **Triggering:** it
+fires on level layout, pacing, encounter, guidance, and reward requests, and
+stays out of systemic mechanic/economy design (`game-design`), narrative
+(`game-storytelling`), and engine-specific level tooling (`godot`/`unity`/
+`unreal`). **Capability:** when engaged, it delivers the craft — the
+blockout→art pipeline, the sawtooth intensity graph with breathers, the
+introduce→develop→twist→combine teaching pattern, light/color/affordance
+guidance, and observe-don't-coach playtesting — rather than generic advice.
+
+## How to run
+
+Run through an agent harness with skills loadable on demand; `cases.yaml` is the
+fixture. Use the same model for every trial; vary only which skills are loaded.
+
+- **Triggering:** load the full catalog so the agent can route to siblings; feed
+  each `should_trigger` / `should_not_trigger` prompt verbatim and record which
+  skill fires. Run 3–5 trials per prompt (the choice is stochastic).
+  - Pass: `should_trigger` selects **level-design** in the majority of trials;
+    `should_not_trigger` does not (ideally routes to the listed `route_to`).
+  - Bar: **≥90%** trigger accuracy across all prompts.
+- **Capability:** run each scenario WITH only level-design loaded vs WITHOUT any
+  skill (baseline), 3 times each. Grade responses against the `must_include`
+  rubric, one point per checkable item genuinely present.
+  - Bar: WITH covers **≥80%** of items on average AND beats WITHOUT by **≥25**
+    percentage points (a skill that doesn't move the needle fails).
+
+## Notes / honesty
+
+- LLM-graded and stochastic — re-run on edits; treat small deltas as noise.
+- `route_to` targets assume the sibling skills (`game-design`,
+  `game-storytelling`, `godot`, `unity`, `unreal`) exist in the catalog; a
+  missing sibling can cause a near-miss to mis-route without it being a
+  level-design fault — note it, don't count it against this skill.

package/skills/shared/level-design/evals/cases.yaml

@@ -0,0 +1,58 @@
+skill: level-design
+
+should_trigger:
+  - prompt: "I've built the first level of my platformer but playtesters say it's boring in the middle and then brutal at the end. How do I fix the pacing?"
+    why: "Direct pacing complaint on a built level — the intensity-graph / sawtooth + breather guidance. 'Boring in the middle, brutal at the end' is a flat-then-spike curve the skill diagnoses."
+  - prompt: "Players keep getting lost in my second map — they wander into dead ends and can't find the exit. What am I doing wrong?"
+    why: "Navigation/readability failure ('players get lost') — the skill's guidance layer: landmarks, light-led critical path, denying wrong turns visually. Lostness is a readability bug the skill owns."
+  - prompt: "How should I lay out the blockout for a new FPS arena before I start making art?"
+    why: "Explicit blockout request and the blockout->greybox->playtest->art pipeline plus metrics block and arena-shape design. Core Use-when trigger."
+  - prompt: "I want to teach the player how a new grappling-hook mechanic works through the level itself, without a tutorial popup. How do I structure that?"
+    why: "Teaching a mechanic through space = introduce->develop->twist->combine. The mechanic itself is game-design's, but structuring the SPACE that teaches it is level design."
+  - prompt: "Where should I put the secret rooms and the best loot in my dungeon so exploring feels rewarding but not frustrating?"
+    why: "Reward & secret placement + risk/reward + breadcrumbing. 'Rewarding but not frustrating' is exactly the reward-the-observation-not-the-pixel-hunt guidance."
+  - prompt: "My combat arena feels like everyone just hides behind one wall and pokes out. How do I make the fights more dynamic?"
+    why: "Arena-shape design: static peek-war means missing flanks/verticality and bad cover rhythm. The skill's encounter/arena section addresses this directly."
+  - prompt: "How do I guide players toward the objective using lighting and color instead of a giant waypoint marker?"
+    why: "Guidance without hand-holding via light/color/composition and the reserved interact-color language. Explicit 'instead of a waypoint' framing is the skill's core."
+
+should_not_trigger:
+  - prompt: "How high should the player be able to jump and how much should double-jump cost stamina? I'm balancing the movement system."
+    route_to: "game-design"
+    why: "This is the movement RULE/economy itself (systemic mechanic + stamina cost tuning), which game-design owns. Level design consumes the jump metric; it doesn't set or balance it."
+  - prompt: "Write the environmental storytelling and the audio-log script for the abandoned lab area to reveal the backstory."
+    route_to: "game-storytelling"
+    why: "Narrative content — what the space SAYS (backstory, audio-log writing). Level design places the beat; game-storytelling authors it."
+  - prompt: "How do I bake the nav mesh and set the agent radius so enemies path around my level geometry in Unity?"
+    route_to: "unity"
+    why: "Engine-specific level tooling (nav-mesh bake, agent radius in Unity). Explicitly out of scope; the engine skill implements the layout the design decided."
+  - prompt: "My Godot TileMap isn't showing collision on the ground layer and the player falls through. How do I fix it?"
+    route_to: "godot"
+    why: "Engine tooling bug — TileMap collision setup in Godot. This is implementation, not the craft of layout/pacing/readability."
+  - prompt: "How should I design the loot rarity tiers and drop-rate curves for the whole game's economy?"
+    route_to: "game-design"
+    why: "Loot-table / economy systems design across the whole game — a systemic concern game-design owns, not the placement of a reward within one level's space."
+  - prompt: "How do I optimize the frame rate in my Unreal level — the shadows and draw calls are tanking performance?"
+    route_to: "unreal"
+    why: "Engine performance/rendering optimization (draw calls, shadow cost) is engine tooling, owned by the unreal skill, not level-design craft."
+
+capability:
+  - scenario: "A designer says: 'My level's first playthrough is fun but by the middle testers get bored and then the final room feels unfairly hard. It's already fully textured and lit. How do I fix it?'"
+    must_include:
+      - "Diagnoses a flawed intensity curve (flat/boring middle, spike at the end) and prescribes a sawtooth: peaks with breathers/safe rooms between, difficulty trending up with checkpoint resets."
+      - "Recommends adding a breather/safe room after peaks so intensity drops and the next peak reads, and varying encounter length/spacing to kill the monotony."
+      - "Flags that the level is already textured/lit as a process problem — layout changes should be validated in blockout/greybox, and warns that art-first makes pacing fixes expensive."
+      - "Frames the final-room spike as a telegraph/difficulty-curve issue (signpost the ramp, reset at a checkpoint) rather than just lowering difficulty."
+  - scenario: "A developer asks: 'Players keep getting lost in my level and walk right past the exit. I don't want to add a waypoint arrow. How do I guide them?'"
+    must_include:
+      - "Treats lostness as a readability/guidance bug, not player error, and keeps guidance diegetic (no waypoint)."
+      - "Uses light to lead (players move toward light/contrast; light the critical path, objective, and exit; keep dead-ends dim)."
+      - "Establishes a dominant landmark per area for self-location and frames the exit with composition/leading lines."
+      - "Recommends a reserved, consistent accent color for interactables/path used nowhere decoratively, and consistent affordances."
+      - "Prescribes watching a fresh, uncoached playtester (and/or position/dwell heatmaps) to locate exactly where players hesitate or diverge, without answering 'where do I go?'."
+  - scenario: "A designer asks: 'I have a new mechanic — a portal gun — and I want the level to teach it without any text tutorial.'"
+    must_include:
+      - "Lays out the introduce -> develop -> twist -> combine progression (or equivalent teach-through-space structure)."
+      - "Introduces the mechanic somewhere it cannot hurt the player (safe, zero-risk first encounter) before any real stakes."
+      - "Builds up through low-stakes use, a recontextualizing twist, and a final combine/mastery test that layers earlier learning."
+      - "Notes that the space itself teaches (no tutorial popup) and that the mechanic's rules belong to game-design while the teaching layout is level design."

package/skills/shared/level-design/references/blockout-to-art.md

@@ -0,0 +1,118 @@
+# Blockout to art — the pipeline in detail
+
+The single most expensive mistake in level design is committing art before the
+space is proven. This reference details each stage, the metrics block that
+everything is built from, how to playtest a grey box, and the handoff to the
+engine skill and art team.
+
+## Why art goes last
+
+A blockout is minutes to change; a finished, textured, lit set-piece is days.
+Layouts *always* change under playtest — a corridor is too long, a fight needs a
+flank, a landmark isn't visible from the entrance. If that geometry is already
+art, every fix throws away work and creates pressure to *not* fix it. Art-first
+levels ship with known layout problems because nobody wants to redo the art.
+So: prove the space grey, then dress it.
+
+## Stage 1 — Blockout (whitebox)
+
+Build the level from **primitive geometry at true scale** — boxes, planes,
+cylinders, ramps. No materials beyond a flat neutral, no props, no final
+lighting. A single neutral mid-grey with a subtle grid texture is ideal: it
+shows scale and stops you from judging the level on looks it doesn't have yet.
+
+You are answering three questions:
+
+1. **Flow** — can the player move through the intended route without snagging?
+   Are the loops, gates, and shortcuts where you planned?
+2. **Timing & distance** — how long is the walk between beats? Are jumps and
+   gaps possible and fair? Is a corridor a slog or a snappy connector?
+3. **Legibility** — from each decision point, is the next objective findable by
+   shape and layout alone (before any lighting/color tricks)?
+
+Block out the **critical path first**, walk it end to end many times, then add
+exploration branches and encounters. Keep everything modular and snapped to a
+grid so pieces move cheaply.
+
+## The metrics block (lock this before any geometry)
+
+Every dimension in the level is a multiple of the player's capabilities. Define
+these **first**, in engine units, and build to them. Guessing metrics is how you
+get gaps that feel wrong and cover that doesn't protect.
+
+| Metric | What it governs | Typical relationship |
+|---|---|---|
+| **Player height (standing)** | Ceiling clearance, door height, sightline height | The base unit; doors ~1.3–1.5× |
+| **Crouch height** | Vents, low cover, crawl spaces | ~0.5–0.6× standing |
+| **Eye height** | What sightlines actually reveal (camera, not feet) | Slightly below standing top |
+| **Shoulder / capsule width** | Corridor and doorway minimum width | Corridors ≥ 2× so two can pass / strafe |
+| **Jump height** | Max step-up, ledge height, low-cover top | Cover just below eye so you can peek |
+| **Jump distance (gap)** | Platform spacing, chasm width | Design gaps at ~70–85% of max so they read as fair |
+| **Reach / grab height** | Climbable ledge height, mantling | Set the climb-ledge trim to this exact height |
+| **Run speed** | Travel time between beats, breather length | Distance = speed × intended seconds |
+| **Weapon/threat effective range** | Arena sightline length, cover spacing | Long lanes for ranged, short for melee |
+
+Write these into `02-DOCS/wiki/stack/level-design.md` (see the SKILL.md grounding
+section) so every level in the project shares one metrics block. When a metric
+is a *rule* of the game (how high the player jumps at all), that number is owned
+by `game-design`; level design *consumes* it here and builds space to fit.
+
+## Stage 2 — Greybox
+
+Refine the blockout just enough to test *reading* and *feel*:
+
+- **Temp neutral materials** to distinguish floor/wall/hazard/interactable by
+  value, not decoration.
+- **Placeholder lighting** used as a *design* tool — light the path, the
+  objective, and the exit; keep non-paths dim. This is where guidance is
+  authored, long before final art lighting.
+- **Stand-in enemies, cover, pickups, and interactables** at real metrics so
+  encounters and the reserved interact-color language can be tested.
+
+Now the questions are: does the space *read*? Does the encounter work? Is the
+pacing right? Greybox is still cheap — you are still iterating layout, not
+protecting art.
+
+## Stage 3 — Playtest the grey box
+
+Do this early and often, on the blockout/greybox, because fixes are cheap. Full
+observation protocol and telemetry live in `guidance-and-readability.md`; the
+blockout-specific loop is:
+
+1. Sit a **fresh, uncoached** player down. Say only "play". Stay silent.
+2. Log every **hesitation** (readability gap), **wrong turn** (navigation gap),
+   **repeated death** (telegraph/difficulty gap), and **skipped area** (reward
+   or guidance gap).
+3. Never answer "where do I go?" — that question is your top finding.
+4. Change the grey geometry/lighting, re-test. Repeat until it plays.
+
+Only when the greybox plays well for players you didn't coach do you unlock art.
+
+## Stage 4 — Art pass (and the handoff)
+
+Art *serves the proven layout*. The reserved interact-color, the light-led path,
+the framed landmark, the readable silhouettes — art must **reinforce** the
+guidance the greybox already established, never fight it. If the art pass makes
+the level prettier but harder to read, it failed.
+
+Hand off to the engine skill (`godot` / `unity` / `unreal`) for the tooling that
+turns the layout into a shippable level:
+
+- Nav-mesh generation and agent radius (must match the capsule width above).
+- Occlusion culling / visibility and streaming volumes.
+- Final lighting: lightmap/GI bakes, reflection probes, light-leak fixes.
+- Collision meshes distinct from render meshes; blocking volumes replacing the
+  greybox's implicit walls.
+- LODs, mesh instancing, and performance budgets.
+
+### Art-pass handoff checklist
+
+- [ ] Layout is locked — no pending "this fight might move" notes.
+- [ ] Metrics block is final; art meshes respect door/corridor/cover heights.
+- [ ] Critical path, landmark, and interact-color language are decided and
+      documented so art reinforces (never contradicts) them.
+- [ ] Greybox lighting intent (path lit, dead-ends dim) is captured for the
+      final lighting pass to honor.
+- [ ] Collision/nav requirements handed to the engine skill with the capsule
+      dimensions.
+- [ ] A greybox reference build is kept for A/B readability comparison after art.