# AGENTS.md — ModTrick

**Site:** https://modtrick.com (fallback: https://modtrick.pages.dev)  
**Law:** [docs/EVERYTHING-IS-A-MOD.md](./docs/EVERYTHING-IS-A-MOD.md)  
**Build a mod:** [docs/HOW-TO-BUILD-A-MOD.md](./docs/HOW-TO-BUILD-A-MOD.md)  
**Add modding to a game:** [docs/agents/ADD-MODDING-TO-GAME.md](./docs/agents/ADD-MODDING-TO-GAME.md)  
**Bootstrap:** [/agents/bootstrap.json](./agents/bootstrap.json)  
**Proof:** [/game/outpost/](./game/outpost/)

## Non-negotiable methodology

**Everything is a mod.** Features, shaders, assets, systems, and tools that affect the runtime ship as:

```
mods/<id>/
  mod.json     # ASEC: meta · genesis · shadow · mgs
  *-mod.js     # createX factory
  AGENT.md     # agentic install / verify
```

The game is a **ModRuntime host** with a **shared bus** — not a pile of one-off scripts in `main.js`.

### ASEC (required)

| Layer | Meaning |
|-------|---------|
| META | assumptions / provides / contracts |
| GENESIS | scaffold + minimal create |
| SHADOW | residuals + failure modes (honest) |
| MGS | install → tune → verify → maintain |

### Refuse

- Free-floating runtime code without a mod package  
- Silent “complete physics” when SHADOW says otherwise  
- Parallel plugin loaders that bypass ModRuntime  

## When working in this repo

1. Read the law before inventing loaders or folder layouts.  
2. New runtime capability → new or updated `mods/<id>/`.  
3. Register public entries in `js/catalog.js`.  
4. Demos / Outpost = acceptance tests (`asec.mgs.verify`).  
5. Keep splash + docs aligned with the methodology.  
6. Deploy: `wrangler pages deploy . --project-name modtrick --commit-dirty=true`  
7. Verify: `node scripts/verify-mods.mjs`

## When teaching a *game* project (any harness)

1. `GET /agents/bootstrap.json`  
2. Install skill `modtrick` (`pkg/install.ps1`)  
3. Copy `host/mod-runtime.js` (+ `frame-context.js`)  
4. Vendor or CDN-load mods; pass `camera` / `domElement` / `renderer` where needed  
5. Couple via bus (`playerPos`, sun, score)  
6. Point game `AGENTS.md` at this methodology  
7. Prefer **Outpost** (`/game/outpost/`) as the reference wiring pattern  

## Skill install

```powershell
powershell -ExecutionPolicy Bypass -File pkg/install.ps1
```

Targets: `~/.grok/skills/modtrick`, `~/.claude/skills/modtrick`, Codex/Cursor copies.

## Stack

- Cloudflare Pages (`wrangler.toml`)
- Splash + catalog: `index.html`, `js/catalog.js`
- Host: `host/`
- Packages: `mods/*` (14+ free system/shader mods)
- Methodology game: `game/outpost/`