# jeo-skills — LLM Installation Delegation Guide

> **For AI agents:** read this guide in full, detect the host OS and installed coding
> agents, then perform the requested installation. The default mode is **full**. Use
> **core only** or **minimal** only when the user explicitly asks for that narrower mode.

> **Preserve existing work:** add or update jeo-skills targets only. Never run a remove,
> clear, reset, or cleanup command against existing skill directories. Never delete an
> unrelated skill or replace an agent's entire configuration file.

## Outcomes and modes

| Mode | Trigger | Outcome |
|---|---|---|
| `full` | Default | Install every jeo-skills skill, register supported MCP/shell tools, and configure detected integrations. |
| `core` | User says “core only” | Install the `starter` bundle through `jeo-skill`; do not install the entire catalog. |
| `minimal` | User says “minimal” | Install only the `jeo-skill` router and its CLI link; skip MCP, shell, and plugin setup. |

A full install installs the skill documents plus the explicitly listed shared tools below.
It does **not** download every app, model weight, media runtime, SDK, or service mentioned
inside all skills. Those remain on demand when a real task selects the corresponding skill.

Every mode also mirrors the skills it installed into any detected Aside account, since the
`skills` CLI cannot target Aside. Minimal mirrors just `jeo-skill`, core mirrors the starter
bundle, full mirrors the whole catalog.

## Step 1 — Detect OS, prerequisites, and coding agents

Determine the platform before choosing paths or package managers:

```bash
case "$(uname -s 2>/dev/null || echo Windows)" in
  Darwin*) PLATFORM=macos ;;
  Linux*) PLATFORM=linux ;;
  MINGW*|MSYS*|CYGWIN*) PLATFORM=windows ;;
  *) PLATFORM=windows ;;
esac

if [ "$PLATFORM" = windows ]; then
  USER_HOME="${USERPROFILE:-$HOME}"
else
  # Resolve the login home independently of $HOME. An Aside bash session points
  # $HOME at its own runtime home, which has no ~/.agents/skills.
  USER_HOME=$(dscl . -read "/Users/$(id -un)" NFSHomeDirectory 2>/dev/null | awk '{print $2}')
  [ -d "${USER_HOME:-}" ] || USER_HOME=$(python3 -c 'import pwd,os; print(pwd.getpwuid(os.getuid()).pw_dir)' 2>/dev/null)
  [ -d "${USER_HOME:-}" ] || USER_HOME="$HOME"
fi
SKILLS_ROOT="$USER_HOME/.agents/skills"
REPO_URL="https://github.com/akillness/jeo-skills"

printf 'platform=%s\nhome=%s\nskills_root=%s\n' "$PLATFORM" "$USER_HOME" "$SKILLS_ROOT"
for cmd in node npm npx python3 claude codex gemini opencode cursor agy pi crush jeo gjc jeopi aside; do
  command -v "$cmd" >/dev/null 2>&1 && printf 'found: %s\n' "$cmd"
done
```

Install only missing prerequisites. Prefer the native package manager:

- macOS: Homebrew (`brew install node python uv`);
- Linux: the detected distro manager, or Snap when that is the managed option
  (`sudo snap install node --classic`; install Python 3 through the distro);
- Windows: Winget (`winget install OpenJS.NodeJS.LTS Python.Python.3.12 astral-sh.uv`),
  then run Bash snippets in Git Bash or WSL2.

Verify Node/npm/npx and Python before continuing:

```bash
node --version
npm --version
npx --version
python3 --version
```

### Running this guide inside an Aside session

Aside's bash tool is not a login shell, and `~/.aside/runtime/env.sh` deliberately points
`HOME`, npm, and pip at Aside's own runtime. Left alone that breaks this guide three ways:
`$HOME/.agents/skills` does not exist, `npm -g` installs into the runtime prefix, and
`pip install --user` fails with `Could not find an activated virtualenv`.

Leave `HOME` itself untouched — Aside owns it, and repointing it redirects Aside-managed
caches and config. Instead use the already-resolved `USER_HOME` for every host path,
prepend absolute host tool paths, and sanitize the npm/pip variables only around host-tool
commands:

```bash
# absolute host paths; derive them, never hardcode a user name or Node version
ASIDE_PATHS="/opt/homebrew/bin:/usr/local/bin:$USER_HOME/.local/bin"
[ -d "$USER_HOME/.pyenv/bin" ] && ASIDE_PATHS="$USER_HOME/.pyenv/bin:$USER_HOME/.pyenv/shims:$ASIDE_PATHS"
# Prefer nvm's own default alias; fall back to any version with an executable node.
# Avoid `sort -V` — older BSD sort on macOS does not support it.
NVM_BIN=""
if [ -r "$USER_HOME/.nvm/alias/default" ]; then
  nvm_alias=$(cat "$USER_HOME/.nvm/alias/default" 2>/dev/null)
  for cand in "$USER_HOME/.nvm/versions/node/$nvm_alias/bin" \
              "$USER_HOME/.nvm/versions/node/v$nvm_alias"*/bin; do
    [ -x "$cand/node" ] && NVM_BIN="$cand" && break
  done
fi
if [ -z "$NVM_BIN" ]; then
  for cand in "$USER_HOME"/.nvm/versions/node/*/bin; do
    [ -x "$cand/node" ] && NVM_BIN="$cand"
  done
fi
[ -n "$NVM_BIN" ] && ASIDE_PATHS="$NVM_BIN:$ASIDE_PATHS"
export PATH="$ASIDE_PATHS:$PATH"

# Aside's runtime npm/pip pins collide with nvm/pyenv and block --user installs
unset NPM_CONFIG_PREFIX NPM_CONFIG_USERCONFIG NPM_CONFIG_CACHE
unset PIP_REQUIRE_VIRTUALENV VIRTUAL_ENV PYTHONNOUSERSITE

uv --version; rtk --version; semble --version   # host tools, once PATH is right
```

Run any command whose output path depends on the home directory with an explicit
per-command override, e.g. `HOME="$USER_HOME" skills add …`, so it lands in the host
`~/.agents/skills` instead of Aside's runtime home. The Step 4 snippets already carry this
prefix; outside Aside it is a no-op because `USER_HOME` equals `$HOME` there.

Under Aside, prefer Homebrew or pyenv installs. macOS security removes unsigned binaries
that curl/tarball installers drop, so the `uv` and `rtk` shell installers below tend to
vanish; tools already installed on the host run fine once `PATH` is set.

## Step 2 — Install the skills CLI

```bash
if ! command -v skills >/dev/null 2>&1; then
  npm install -g skills
fi
skills --version
```

## Step 3 — Build non-duplicating agent targets

The skills CLI accepts runtime IDs, not executable names. Always target `universal`; it
populates `~/.agents/skills`, which Codex, Gemini CLI, OpenCode, Cursor, jeo-code, GJC,
and jeopi can share. Add a dedicated target only when that runtime uses a distinct root.
Do **not** pass unsupported IDs such as `jeo`, `gjc`, `jeopi`, or `aside`.

```bash
SKILLS_AGENT_ARGS=(-a universal)
command -v claude >/dev/null 2>&1 && SKILLS_AGENT_ARGS+=(-a claude-code)
(command -v agy >/dev/null 2>&1 || command -v antigravity >/dev/null 2>&1) \
  && SKILLS_AGENT_ARGS+=(-a antigravity)
(command -v pi >/dev/null 2>&1 && [ -d "$USER_HOME/.pi/agent" ]) \
  && SKILLS_AGENT_ARGS+=(-a pi)
command -v crush >/dev/null 2>&1 && SKILLS_AGENT_ARGS+=(-a crush)
printf 'skills targets:'; printf ' %q' "${SKILLS_AGENT_ARGS[@]}"; printf '\n'
```

`codex`, `gemini-cli`, `opencode`, and `cursor` also map to the shared root, so adding
all of those alongside `universal` would create redundant platform exposure rather than
additional skills.

Aside is not a skills CLI runtime at all and does not read the shared root; it loads
per-account skills from its own directory. Step 4 mirrors the installed skills there.

## Step 4 — Install the requested scope

### Default: full

Unless the user said “core only” or “minimal”, install every live skill:

```bash
HOME="$USER_HOME" skills add -g "$REPO_URL" --skill '*' "${SKILLS_AGENT_ARGS[@]}" --yes --copy --full-depth
```

### Core only

```bash
HOME="$USER_HOME" skills add -g "$REPO_URL" --skill jeo-skill "${SKILLS_AGENT_ARGS[@]}" --yes --copy --full-depth
HOME="$USER_HOME" python3 "$SKILLS_ROOT/jeo-skill/scripts/jeo-skill.py" link
HOME="$USER_HOME" jeo-skill install --bundle starter --global --yes
```

### Minimal

```bash
HOME="$USER_HOME" skills add -g "$REPO_URL" --skill jeo-skill "${SKILLS_AGENT_ARGS[@]}" --yes --copy --full-depth
HOME="$USER_HOME" python3 "$SKILLS_ROOT/jeo-skill/scripts/jeo-skill.py" link
HOME="$USER_HOME" jeo-skill doctor
```

The `HOME="$USER_HOME"` prefix is what makes these land in the host `~/.agents/skills`.
Outside Aside it is a harmless no-op, since `USER_HOME` already equals `$HOME`. Inside an
Aside session, a bare `skills add` would install into `~/.aside/runtime/home/.agents/skills`
and the Aside mirror below would then find nothing to copy.

### Mirror the installed skills into Aside (all modes)

Run this in every mode, including minimal, whenever Aside is present. The `skills` CLI has
no Aside runtime ID, and Aside loads account skills from:

```text
<asideHome>/u/<accountId>/skills/user/<skill-name>/SKILL.md
```

Scope the name set to the mode you just installed, then copy only names that are both in
the jeo-skills catalog and actually present in `$SKILLS_ROOT`. Never mirror the whole
shared root — it holds skills from other sources.

```bash
ASIDE_HOME="$USER_HOME/.aside"
ASIDE_MODE=full   # full | core | minimal — match the mode you installed

# Call the router by absolute path. In full mode `link` has not run yet, so the
# `jeo-skill` command is not on PATH; relying on it would silently yield no names.
JEO_ROUTER="$SKILLS_ROOT/jeo-skill/scripts/jeo-skill.py"

case "$ASIDE_MODE" in
  minimal) ASIDE_NAMES="jeo-skill" ;;
  core)    ASIDE_NAMES=$(HOME="$USER_HOME" python3 "$JEO_ROUTER" install -b starter --dry-run \
             | sed -n 's/^Selected [0-9]* skill(s): //p' | tr ',' '\n' | tr -d ' ') ;;
  *)       ASIDE_NAMES=$(HOME="$USER_HOME" python3 "$JEO_ROUTER" list --json \
             | python3 -c 'import json,sys; print("\n".join(s["name"] for s in json.load(sys.stdin)))') ;;
esac

if [ ! -d "$ASIDE_HOME/u" ]; then
  printf 'aside: not installed, skipping mirror\n'
elif [ -z "${ASIDE_NAMES:-}" ]; then
  printf 'aside: ERROR could not resolve catalog names from %s — mirror skipped, report this\n' "$JEO_ROUTER" >&2
else
  for acct in "$ASIDE_HOME"/u/*/; do
    [ -d "$acct/skills" ] || continue
    dest="${acct%/}/skills/user"
    mkdir -p "$dest"
    synced=0
    while IFS= read -r name; do
      [ -n "$name" ] || continue
      [ -f "$SKILLS_ROOT/$name/SKILL.md" ] || continue
      mkdir -p "$dest/$name"
      cp -R "$SKILLS_ROOT/$name/." "$dest/$name/" && synced=$((synced + 1))
    done <<EOF
$ASIDE_NAMES
EOF
    printf 'aside_synced=%s -> %s\n' "$synced" "$dest"
  done
fi
```

Constraints for this step:

- Discover accounts from directory names under `$ASIDE_HOME/u` only. Never read
  `~/.aside/accounts.json`; it holds live access tokens.
- Never touch `skills/builtin/`. It is checksum-tracked by `.bootstrap-manifest.json`.
- Never delete anything under `skills/user/`. Unrelated user skills must survive; the copy
  refreshes jeo-skills entries in place and is safe to re-run.
- `cp -R "$src/."` (trailing `/.`) copies contents into an existing directory on both BSD
  and GNU `cp`, so nested `scripts/` and `references/` land correctly instead of nesting twice.
- Aside parses ordinary YAML frontmatter, so the catalog's folded `description: >` blocks
  load as-is. The stricter double-quoted rule in Aside's bundled `skill-creator` is a style
  lint for newly authored skills, not a loader requirement.
- Resolve names through `python3 "$JEO_ROUTER"`, never the bare `jeo-skill` command. The
  router falls back to the remote catalog and `~/.cache/jeo-skill/skills.json`, so it works
  before `link` runs. An empty name set is an error to report, never a silent no-op.
- Inside an Aside session, apply the Step 1 preamble first, and prefix the router with
  `HOME="$USER_HOME"` if a command's output path depends on the home directory.

Stop here in minimal mode. In core mode, install only dependencies explicitly required
by the selected starter skills; do not continue into the full shared-tool setup by default.

## Step 5 — Full-mode shared tools

Run this step only in full mode. Reuse working installations and make every registration
idempotent: inspect/list first, add only when missing, and never rewrite a whole config.

### RTK shell output compaction

```bash
if ! command -v rtk >/dev/null 2>&1; then
  if command -v brew >/dev/null 2>&1; then
    brew install rtk
  elif [ "$PLATFORM" = windows ]; then
    printf '%s\n' 'Install the matching rtk.exe from https://github.com/rtk-ai/rtk/releases or use WSL2.'
  else
    # Unreliable inside an Aside session: macOS removes the unsigned binary this drops.
    curl -fsSL https://raw.githubusercontent.com/rtk-ai/rtk/refs/heads/master/install.sh | sh
    export PATH="$USER_HOME/.local/bin:$PATH"
  fi
fi
command -v rtk >/dev/null 2>&1 && rtk init -g
```

Do not use `cargo install rtk`; crates.io contains an unrelated package with that name.

### Semble CLI and MCP server

```bash
if ! command -v uvx >/dev/null 2>&1; then
  if command -v brew >/dev/null 2>&1; then
    brew install uv
  elif [ "$PLATFORM" = windows ]; then
    powershell -NoProfile -Command "irm https://astral.sh/uv/install.ps1 | iex"
  else
    # Unreliable inside an Aside session: macOS removes the unsigned binary this drops.
    curl -LsSf https://astral.sh/uv/install.sh | sh
    export PATH="$USER_HOME/.local/bin:$USER_HOME/.cargo/bin:$PATH"
  fi
fi
command -v semble >/dev/null 2>&1 || uv tool install 'semble[mcp]'

if command -v claude >/dev/null 2>&1 && ! claude mcp list 2>/dev/null | grep -q '^semble'; then
  claude mcp add semble -s user -- uvx --from 'semble[mcp]' semble
fi
if command -v codex >/dev/null 2>&1 && ! codex mcp list 2>/dev/null | grep -q '^semble'; then
  codex mcp add semble -- uvx --from 'semble[mcp]' semble
fi
```

For another detected agent, use its documented MCP command/config surface; do not guess a
JSON/TOML schema or overwrite its existing settings.

### Ouroboros (`ooo`) MCP server

```bash
if ! command -v ouroboros >/dev/null 2>&1; then
  if command -v uv >/dev/null 2>&1; then
    uv tool install 'ouroboros-ai[all]'
  else
    python3 -m pip install --user 'ouroboros-ai[all]'
  fi
fi

if command -v claude >/dev/null 2>&1 && ! claude mcp list 2>/dev/null | grep -q '^ooo'; then
  claude mcp add ooo -s user -- ouroboros mcp serve
fi
if command -v codex >/dev/null 2>&1 && ! codex mcp list 2>/dev/null | grep -q '^ooo'; then
  codex mcp add ooo -- ouroboros mcp serve
fi
```

### Aside MCP wiring

Aside handles MCP in two directions, and only one of them is scriptable.

**Aside as an MCP server.** `aside mcp` starts Aside over stdio, letting another agent
drive its browser session. Register it idempotently:

```bash
if command -v aside >/dev/null 2>&1; then
  if command -v claude >/dev/null 2>&1 && ! claude mcp list 2>/dev/null | grep -q '^aside'; then
    claude mcp add aside -s user -- aside mcp
  fi
  if command -v codex >/dev/null 2>&1 && ! codex mcp list 2>/dev/null | grep -q '^aside'; then
    codex mcp add aside -- aside mcp
  fi
fi
```

**Servers Aside itself consumes.** These live in `<asideHome>/u/<accountId>/settings.json`
under an app-managed `mcp.servers` map, alongside `mcp.inventories` and a separate
`~/.aside/mcp-credential-cleanup.json`. Aside's own `aside.settings` API exposes no MCP key,
so the daemon owns that schema and its credential handling. Do not hand-edit it or guess the
shape; add servers through Aside's own MCP settings UI and report that as a manual follow-up.

### Claude Code orchestration plugin

When Claude Code is detected, install the official marketplace plugin without removing
or replacing existing plugins:

```bash
if command -v claude >/dev/null 2>&1; then
  claude plugin marketplace add https://github.com/Yeachan-Heo/oh-my-claudecode || true
  claude plugin install oh-my-claudecode || true
fi
```

If the installed Claude version does not expose non-interactive plugin commands, report
these two commands for the user to run through Claude Code's `/plugin` interface instead
of editing plugin configuration by hand.

### Codex OMC hook compatibility

OMC 4.15.7 emits Claude-only `suppressOutput` fields from three `PostToolUse`
handlers. Codex rejects that field at its plugin boundary. When both Codex and
the installed repair helper are present, repair only that known cached version;
all other plugin caches remain untouched.

```bash
if command -v codex >/dev/null 2>&1 \
  && [ -x "$SKILLS_ROOT/jeo-skill/scripts/repair-codex-omc-posttool-hooks.sh" ]; then
  bash "$SKILLS_ROOT/jeo-skill/scripts/repair-codex-omc-posttool-hooks.sh"
fi
```

### Animato animation runtime (on demand)

The `animato` skill installs as documents plus stdlib-only scripts; it never installs Blender,
the upstream server, or a model key. Set those up only when a task actually animates a model:

```bash
# 1. upstream server (Python 3.13 + uv; bpy is a project dependency, no Blender install)
git clone https://github.com/otdnnc/Animato.git && cd Animato && uv sync
uv run fastapi run main.py            # UI + API on http://localhost:8000

# 2. the key the agent loop spends (free tier is enough — one inference per animation)
export ANIMATO_API_KEY=...            # or GEMINI_API_KEY / OPENAI_API_KEY

# 3. verify wiring, then the loop itself
python3 "$SKILLS_ROOT/animato/scripts/selftest.py"      # offline: stub server + stub LLM
python3 "$SKILLS_ROOT/animato/scripts/animato_agent.py" doctor
```

`selftest.py` needs neither the server nor a key, so it is safe to run during installation
verification. Skip steps 1–2 unless the user asked for animation work: `/api/run` and `/api/chat`
execute model-written Python by design and must stay on a trusted local machine.

### UniRig rigging runtime (on demand)

The `unirig` skill installs as documents plus shell/Python wrappers; it never clones the
upstream repository, downloads checkpoints, or installs CUDA wheels during setup. UniRig
inference needs Python 3.11 and an NVIDIA GPU, so prepare it only when a task actually rigs
a model:

```bash
# 1. readiness first — every blocking item is reported before any GPU work
bash "$SKILLS_ROOT/unirig/scripts/doctor.sh"

# 2. upstream checkout + dependencies (CUDA tag must match the machine)
bash "$SKILLS_ROOT/unirig/scripts/install.sh" --repo-only          # checkout only
bash "$SKILLS_ROOT/unirig/scripts/install.sh" --cuda cu121         # checkout + venv + deps

# 3. plan a run without executing it (works on any machine, including macOS)
bash "$SKILLS_ROOT/unirig/scripts/rig.sh" --input model.glb \
     --output out/model_rigged.glb --dry-run
```

`doctor.sh` and `rig.sh --dry-run` need neither a GPU nor the checkout, so both are safe during
installation verification. Skip step 2 unless the user asked for rigging work on a CUDA machine;
on macOS or a CPU-only box, route out per `unirig/references/route-outs-and-troubleshooting.md`
instead of forcing the install.

### NightRun bare-metal LLM runtime (on demand)

The `nightrun` skill installs as documents plus a read-only `doctor` wrapper; it never
clones `hardrave/NIGHTRUN`, builds firmware, or flashes any media during setup. It targets
building/flashing a bare-metal `no_std` Rust UEFI LLM appliance, so prepare it only when a
task actually needs to build, convert a model, or boot the image:

```bash
# 1. clone on demand, never during install
git clone https://github.com/hardrave/NIGHTRUN.git

# 2. read-only prerequisite report (Rust nightly, QEMU, free disk) — writes nothing
bash "$SKILLS_ROOT/nightrun/scripts/nightrun.sh" doctor NIGHTRUN
```

Never run `./install.sh` (real USB/SD flashing) or auto-answer its `FLASH /dev/sdX`
confirmation as part of setup or automation; that step must stay a manual, interactive
choice by the user. See `nightrun/references/commands.md` for the full build/convert/QEMU
command reference.

### Soup LLM fine-tuning CLI (on demand)

The `soup` skill installs as documents plus a read-only `doctor` wrapper; it never runs
`pip install soup-cli` or starts a training job during setup. It targets `soup-cli`
(fine-tuning/post-training LLMs), so prepare it only when a task actually needs to pick a
training method, estimate cost/memory, or run `soup train`:

```bash
# 1. read-only environment report (python, soup, torch/transformers/peft/trl, GPU backend) — installs nothing
bash "$SKILLS_ROOT/soup/scripts/soup.sh" doctor

# 2. only after the user confirms the install profile
pip install soup-cli            # light CLI: init/advise/data/profile/cost
pip install "soup-cli[train]"   # + torch/transformers/peft/trl for real training
```

Never auto-run `soup train` (starts a real training job/spends GPU time) as part of setup
or verification; that step must stay a task-triggered, user-confirmed action. See
`soup/references/commands.md` for the full command reference.
### Watermarks Remover heavy backends (on demand)

The `watermarks-remover` skill installs as documents plus a read-only `doctor` wrapper over
the upstream stdlib scripts; it never clones `guillaumemeyer/watermarks-remover` or installs
the optional SynthID/CtrlRegen backends during setup:

bash
# 1. clone on demand, never during install
git clone https://github.com/guillaumemeyer/watermarks-remover.git

# 2. read-only prerequisite report (python, c2patool, exiftool) — installs nothing
bash "$SKILLS_ROOT/watermarks-remover/scripts/watermarks-remover.sh" doctor watermarks-remover


Never auto-run `setup_synthid.sh` / `setup_ctrlregen.sh` (each downloads ~10 GB of model
weights) as part of setup or verification; those stay a task-triggered, user-confirmed
choice. See `watermarks-remover/references/commands.md` for the full script reference.

### SV Number MCP server (on demand)

The `mcp-server-sv-number` skill installs as documents only; it never registers the MCP
server or orders a number during setup. Every `order_number` call spends real money against
the user's SV Number account balance, so treat activation as a task-triggered, user-confirmed
action, never a setup/verification step:

bash
# 1. clone/install on demand, never during install
git clone https://github.com/sv-number/mcp-server.git


See `mcp-server-sv-number/references/setup.md` for the API-key/config and MCP client
registration steps, and confirm the target country/service with the user before ordering.

### KADATH agent evolution runs (on demand)

The `kadath` skill installs as documents only; it never starts `./kadath.sh` or a Docker
Compose stack during setup. Each generation of a KADATH run spends real OpenAI API cost and
container compute, so prepare it only when a task actually needs an evolutionary agent-benchmark
run, and always route the approval gate through the user:

bash
# clone on demand, never during install
git clone https://github.com/i3T4AN/KADATH.git


Never auto-approve a locked benchmark or auto-run `kadath run`/`kadath.sh` as part of setup
or verification; propose → approve → run must stay explicit, user-confirmed steps. See
`kadath/references/commands.md` for the full CLI reference.


### WAI Play web-game testing runtime (on demand)

The `wai-play` skill installs as documents plus a read-only `doctor` wrapper and a
stdlib-only static checker; it never clones `waiterve/wai-play`, installs Streamlit or
Playwright, downloads a Chromium build, or starts a playtest during setup. Prepare it only
when a task actually needs to playtest a web game:

```bash
# 1. read-only environment report (python, streamlit/playwright/openai/dotenv, Chromium, .env key NAMES) — installs nothing
bash "$SKILLS_ROOT/wai-play/scripts/wai-play.sh" doctor

# 2. static contract check on a game's integration file — reads the file, runs nothing
python3 "$SKILLS_ROOT/wai-play/scripts/check_integration.py" \
  --game-type survivor_like path/to/game-integration.js

# 3. only after the user asks for a real playtest
git clone https://github.com/waiterve/wai-play.git && cd wai-play
python3 -m venv .venv && source .venv/bin/activate
python -m pip install -r requirements.txt && python -m playwright install chromium
cp .env.example .env            # add DeepSeek + Kimi keys; keyless runs work but are degraded
streamlit run app.py
```

Both step-1 and step-2 commands are safe during installation verification: `doctor` reports
`.env` key names only and never their values, and `check_integration.py` is a static text
check that starts no browser. Skip step 3 unless the user asked for a playtest; it launches
a local web service that drives a real browser. Test only games and source the user owns or
is authorized to test, and disclose that AI source modeling sends source summaries to the
configured third-party providers.

### Godogen autonomous game generator (on demand, can delete files and spend money)

The `godogen` skill installs as routing documents, a read-only host/publish inspector, and an
offline cost calculator. Blanket setup must not clone `htdt/godogen`, install Godot/Rust/Node
or GPU Python dependencies, run `publish.sh`, launch an engine or browser, or call Gemini,
Grok, or Tripo3D. Prepare a lane only when a task actually needs Godogen:

```bash
# 1. read-only host report; provider keys are SET/MISSING only and values are never printed
bash "$SKILLS_ROOT/godogen/scripts/godogen.sh" doctor all

# 2. read-only preview; creates no target and blocks unsafe nonempty/symlink targets
bash "$SKILLS_ROOT/godogen/scripts/godogen.sh" plan \
  --engine godot --agent claude --out /path/to/new-empty-game

# 3. offline estimate at the pinned upstream rates; makes no provider request
python3 "$SKILLS_ROOT/godogen/scripts/cost-estimate.py" \
  --gemini-1k 1 --rig 1 --retarget 3
```

Steps 1-3 are safe during installation verification. `doctor` runs version/presence checks
only, `plan` never invokes upstream `publish.sh`, and the estimator uses Python's standard
library with zero network requests. Missing engine tools or API keys are lane readiness facts,
not reasons for setup to install anything.

Never run Godogen's `publish.sh --force` during setup: at the pinned upstream commit it removes
the entire resolved target with `rm -rf`. Even a normal publish uses `rsync --delete` on the
whole `.claude/skills/` or `.agents/skills/` directory and can erase unrelated sibling skills.
Prefer a fresh empty target. A normal re-publish is allowed only when the helper recognizes
the same agent/engine runtime and finds no sibling skill beside `asset-gen`; commit or back up
the game repo first and never add `--force`. Show the exact path and keep any forced publish
user-confirmed.

Paid asset generation is also task-triggered and confirmation-gated. Show operation counts and
a cost ceiling before the first call. If Tripo3D times out, preserve `<output>.tripo.json` and
run `asset_gen.py resume -o <output>`; never resubmit a pending `glb`, `rig`, or `retarget` job
because it can double-charge. See `godogen/references/upstream-and-publish.md` and
`godogen/references/asset-generation.md` before a real publish or spend.

### goalflow LangGraph framework (on demand)

The `goalflow` skill installs as documents plus a read-only `doctor` wrapper and two
stdlib-only checkers; it never clones `wanmol/goal-flow`, installs LangGraph/FastAPI,
provisions Redis or MySQL, or starts the server during setup. Prepare it only when a task
actually needs to transpile a Dify flow, build a workflow, or run the engine:

```bash
# 1. read-only environment report (python 3.12, langgraph/fastapi/redis/pymysql, .env key NAMES) — installs nothing
bash "$SKILLS_ROOT/goalflow/scripts/goalflow.sh" doctor
bash "$SKILLS_ROOT/goalflow/scripts/goalflow.sh" doctor /path/to/goal-flow

# 2. static pre-publish security gate on a checkout — reads files and git metadata, runs nothing
python3 "$SKILLS_ROOT/goalflow/scripts/preflight_audit.py" /path/to/goal-flow

# 3. static check of a runtime SKILL.md (goalflow's own skills/, not this catalog)
python3 "$SKILLS_ROOT/goalflow/scripts/check_goalflow_skill.py" --all /path/to/goal-flow/skills

# 4. only after the user asks to actually run it — needs Redis + MySQL
git clone https://github.com/wanmol/goal-flow.git && cd goal-flow
python3 -m venv venv && source venv/bin/activate
pip install -e .                 # installs goalflow + the vendored agent_kit
cp .env.example .env             # fill in real values; never commit it
goalflow-server                  # http://localhost:8000
```

Steps 1–3 are safe during installation verification: `doctor` reports `.env` key names only
and never their values, and both Python checkers are static readers that start no server and
open no database connection. Skip step 4 unless the user asked to run the engine — it needs
Redis and MySQL, and MySQL backs the LangGraph checkpointer that stop/resume and HITL depend on.

Run `preflight_audit.py` before helping anyone push a goalflow fork to a shared or public
remote. Upstream's own checklist warns that untracking `.env` does not remove it from git
history; the published repo is already scrubbed, but internal forks and clones predating the
scrub still carry live credentials that must be rotated, not merely scrubbed.

### Mole macOS maintenance CLI (on demand, deletes files)

The `mole` skill installs as documents plus a read-only helper; it never runs `brew install mole`,
never pipes `install.sh` into bash, and never runs a cleanup during setup. Mole deletes files on
the user's live machine and `mo clean` / `mo purge` / `mo installer` delete **permanently**, so
installation and every destructive run stay task-triggered and user-confirmed:

```bash
# 1. read-only readiness report (macOS/arch, mo presence + install channel, fd, config, logs) — installs nothing
bash "$SKILLS_ROOT/mole/scripts/mole.sh" doctor

# 2. print the agent-facing JSON surfaces — runs no Mole command at all
bash "$SKILLS_ROOT/mole/scripts/mole.sh" surfaces

# 3. only after the user asks for Mole
brew install mole
```

Steps 1–2 are safe during installation verification; step 2 only prints documentation. Skip step 3
unless the user asked for Mole. The helper's `json` subcommand is hard-restricted to `status`,
`analyze`, and `history` so a destructive command is not reachable through it. Never run
`mo clean`, `mo uninstall`, `mo purge`, `mo installer`, `mo optimize`, `mo remove`, or `mo update`
(especially `--nightly`, which installs unreleased `main`) as part of setup or verification — always
`--dry-run` first and let the user run the real command. macOS only. See
`mole/references/safety.md` for the protection model and `mole/references/commands.md` for the full
command/env reference.

### OpenStory AI video stack (on demand)

The `openstory` skill installs as documents plus a read-only helper; it never clones
`openstory-so/openstory`, runs `bun install`, migrates a database, or deploys anything during
setup. Its `doctor`/`env-check` commands only inspect the host and report env var **names**,
never values. Prepare the stack only when a task actually needs to run or modify OpenStory:

```bash
# 1. read-only readiness report (bun/node engine range, repo, node_modules, .env.local) — installs nothing
bash "$SKILLS_ROOT/openstory/scripts/openstory.sh" doctor .

# 2. env presence by NAME only — never prints a value
bash "$SKILLS_ROOT/openstory/scripts/openstory.sh" env-check /path/to/openstory

# 3. only after the user asks to run it
git clone https://github.com/openstory-so/openstory.git
cd openstory && bun install && bun dev     # http://localhost:3000
```

Steps 1–2 are safe during installation verification. Skip step 3 unless the user asked for a
local stack: `bun dev` writes `.env.local`, migrates and seeds a local D1, and starts a
Workerd server. Never add AI keys, run `bun setup`, or trigger a generation as part of setup —
`FAL_KEY` spends real money per call. Never run `bun db:migrate:prd`, `bun deploy`,
`bun deploy:production`, or `bun cf:deploy:prd` during setup or verification; production
deploys and remote D1 migrations stay task-triggered and user-confirmed. See
`openstory/references/commands.md` for the full script/env reference and
`openstory/references/troubleshooting.md` for the documented D1 CASCADE and remote-binding
hazards.

### OpenMontage agentic video production (on demand)

The `openmontage` skill installs as original routing documents plus read-only checkout,
pipeline, and project inspectors. Blanket setup must not clone `calesthio/OpenMontage`, run
`make setup`, import its provider registry, install Python/Node/GPU packages, warm an npx
cache, start Backlot, render a demo, or call a media provider. Inspect only when a task
actually chooses OpenMontage:

```bash
# 1. host and checkout inspection only; no installs and no credential values
bash "$SKILLS_ROOT/openmontage/scripts/openmontage.sh" doctor /path/to/OpenMontage

# 2. dependency-free YAML/director inventory; does not import upstream Python
bash "$SKILLS_ROOT/openmontage/scripts/openmontage.sh" pipelines \
  /path/to/OpenMontage --strict

# 3. only after the user asks to prepare a working checkout
#    upstream had no release tags at the skill audit, so use the audited commit for a stable start
git clone https://github.com/calesthio/OpenMontage.git
cd OpenMontage
git checkout cd9f3c1f03368be87b140af494914b8ee4e3c7a4
make setup

# 4. after dependencies are intentionally installed, discover capabilities without a provider call
bash "$SKILLS_ROOT/openmontage/scripts/openmontage.sh" preflight .
```

Steps 1–2 are safe during installation verification. They read repository structure and
host versions only; `doctor` reports `.env` tracking and `pipelines --strict` parses a
small YAML subset with the Python standard library. Steps 3–4 are task-triggered because
`make setup` creates `.venv`, downloads Python/npm/Piper dependencies, and creates `.env`
from the example when absent; preflight imports the selected upstream checkout.

Do not run `make install-gpu`, `make demo`, `make hyperframes-warm`,
`scripts/backlot_simulate_run.py`, a Backlot server, or any provider integration during
setup verification. A real production must run `provider_menu_summary()` first, announce
the exact tool/provider/model and sample-versus-batch scope, show a cost ceiling, and obtain
approval before each new paid path. Never print, copy, or commit credential values. Human
approval gates in `pipeline_defs/*.yaml` are binding and require an `awaiting_human`
checkpoint plus a later explicit approval before work continues.

OpenMontage upstream is AGPL-3.0. Preserve its license and notices, keep the exact source
revision, and review source-offer obligations before distributing or serving a modified
version. See `openmontage/references/upstream-and-setup.md` for install and licensing
boundaries and `openmontage/references/production-contract.md` before a real production.

### ZeroShot multi-agent execution (on demand)

The `zeroshot` skill installs as routing documents plus two read-only helpers. Blanket
setup must not install either upstream product, enter the guided wizard, apply settings,
start or resume a provider run, create a worktree or branch, mount credentials, open a
PR, merge, schedule work, export private logs, or remove durable state. Inspect only when
a task explicitly chooses ZeroShot:

```bash
# 1. host, repo, binary, settings-presence, and durable-state counts only
#    environment variables are reported as SET or MISSING; values are never printed
bash "$SKILLS_ROOT/zeroshot/scripts/zeroshot.sh" doctor /path/to/repo

# 2. safe only when the Node product is already installed
#    upstream tests require this plan to omit secret-shaped fields; it writes nothing
command -v zeroshot >/dev/null 2>&1 && \
  bash "$SKILLS_ROOT/zeroshot/scripts/zeroshot.sh" setup-plan /path/to/repo

# 3. only after the user selects the established Node product
#    pin the successful release rather than the moving main audit commit
npm install -g @the-open-engine/zeroshot@6.45.0
zeroshot --version
```

Steps 1 and 2 are safe during installation verification. `doctor` invokes only version
flags when a ZeroShot binary exists; it never invokes a provider or run. `setup-plan`
delegates to `zeroshot setup plan --json`, not
`setup apply`. Skip step 3 unless the user asks to use the product: global npm install
runs upstream lifecycle scripts and can build generated output, adjust native package
permissions, inspect PATH, and print the setup invitation. Do not run bare `zeroshot`
because first use can enter an interactive wizard.

The standalone native product is separate. Install it only for a concrete Rust, Windows,
JSON/NDJSON, named-target, or Python-SDK requirement:

```bash
npm install -g @the-open-engine/zeroshot-rust@0.4.0
zeroshot-rust version
```

Its npm installer selects a declared platform archive and verifies release SHA-256 sums.
The source Python SDK advertised `pip install zeroshot-rust`, but PyPI returned 404 and
the trusted-publishing job failed when this skill was audited. Recheck the registry
before recommending that command; never substitute an unverified wheel URL.

A real Node run must freeze one bounded task, observable acceptance, provider/model,
agent topology, iteration ceiling, explicit worktree or reviewed Docker isolation,
credential and network scopes, delivery mode, and cost ceiling. Use the no-execution
preflight and then wait for approval:

```bash
bash "$SKILLS_ROOT/zeroshot/scripts/zeroshot.sh" preflight \
  --repo /path/to/repo \
  --input 'Add JSON output with tests' \
  --isolation worktree \
  --delivery none \
  --provider codex
```

The helper prints a shell-quoted proposal but never runs it. Current-checkout mutation
and ship behavior have explicit approval guards. PR creation, merge, each new paid turn,
resume, `finish`, schedules, credential forwarding, `stop`, `kill`, `force-stop`, `gc`,
`clean`, `purge`, updates, uninstall, and publication remain separately confirmed actions.
Logs and exports can contain prompts, source, tool data, and provider output. Use
`trace_summary.py` for content-free structural checks. See
`zeroshot/references/product-and-installation.md` and
`zeroshot/references/providers-and-security.md` before installing or executing.

### Unity Technologies official skill pack (on demand)

When the user explicitly names `Unity-Technologies/skills`, the official Unity Skills collection, or asks to inspect/install/refresh one of its upstream sub-skills:

- Load `.agent-skills/unity-technologies-skills/SKILL.md` first.
- Pin and audit the actual `skills/` tree, Unity Companion License, frontmatter, support files, and destination before copying anything.
- Default to a named selective install. The audited pin has 22 source directories but 21 Agent Skills CLI discoveries because `physics-3d-collision` has invalid YAML, and the pack's `unity-cli` collides with the existing local skill.
- Keep skill installation separate from Editor/module/package changes, live C# evaluation, project mutation, Git publication, UGS deployment, licensing, purchases, ads, privacy settings, credentials, builds, and tests. Preview and confirm each side-effect class separately.
- Route generic third-party Unity pack curation to `unity-gamedev-skill-pack`, build-log failures to `game-build-log-triage`, game CI design to `game-ci-cd-pipeline`, and profiler interpretation to `game-performance-profiler`.

### Solo Skills personal automation pack (on demand)

When the user explicitly names `bam-bam-2/solo-skills`, Solo Skills, its 26-skill public collection, or `fleet.md`:

- Load `.agent-skills/solo-skills/SKILL.md` first.
- Treat the repository as one author's personal operating system that requires selective adaptation, not as 26 portable drop-in tools. Audit paths, hosts, IDs, account assumptions, credential sources, schedules, provider calls, support scripts, permission bypasses, live switches, and destination collisions before installation.
- The audited pin has 26 source directories but 24 Agent Skills CLI discoveries because `style-skill-creator` and `voice-dna-creator` have invalid YAML. The local `harness` is canonical and must not be overwritten. `fleet.md` claims 49 automations, but its category headings sum to 48; neither number proves those jobs exist in the current environment.
- Keep outbound messages, publishing, Notion archives, mail, Threads, Discord, KakaoTalk, SSH, desktop control, launchd, persistent agents, paid providers, and credential use in preview or dry-run mode until the exact identity, target, payload, timing, cost, rollback, and validation are confirmed.
- Route generic agent-team design to `harness` and reusable skill authoring to `skill-standardization` or `write-a-skill`.

### Drama Skills short-drama suite (on demand)

The `drama-skills` catalog entry installs as routing documents plus a read-only helper. It
never clones or links `zenstory-ai/drama-skills`, starts its local Dashboard, runs upstream
Python, or calls a media provider during blanket setup. The upstream repository is a separate
suite of ten independently installable skills; prepare it only when a task actually needs a
Chinese short-drama or motion-comic workflow:

```bash
# 1. host and checkout inspection only — no upstream code is executed
bash "$SKILLS_ROOT/drama-skills/scripts/drama-skills.sh" doctor /path/to/drama-skills
bash "$SKILLS_ROOT/drama-skills/scripts/drama-skills.sh" routes

# 2. stable upstream checkout, only after the user asks to use the suite
#    v0.6.0 is the creator-first five-document release; main may be newer
mkdir -p "$USER_HOME/.local/share"
DRAMA_REPO="$USER_HOME/.local/share/drama-skills"
if [ -e "$DRAMA_REPO" ]; then
  printf 'drama-skills checkout already exists: %s (inspect it; do not overwrite)\n' "$DRAMA_REPO"
else
  git clone --branch v0.6.0 --depth 1 \
    https://github.com/zenstory-ai/drama-skills.git "$DRAMA_REPO"
fi

# 3. inspect a real project without changing it
bash "$SKILLS_ROOT/drama-skills/scripts/drama-skills.sh" project /path/to/project
```

The helper is safe during installation verification: it reads paths, checks Python 3.9+ and
the expected ten `SKILL.md`/`selftest.py` pairs, reports the checkout commit, and prints only
whether `ARK_API_KEY`, `OPENAI_API_KEY`, and `MINIMAX_API_KEY` are set. It does not print
values, run self-tests, create symlinks, start the Dashboard, confirm a job, or expose any
provider command.

Skip the clone and links unless the user selected this workflow. When installing upstream,
pin a tag or commit before linking individual `skills/*` directories into a runtime; never
install `maintainers/skills/short-drama-knowhow`, and never overwrite unrelated existing
skills. v0.6 is a breaking creator-first change from v0.5, so do not mix both formats in one
project. A symlink to a moving `main` silently changes agent instructions after `git pull`.

Normal writing, assets, prompts, storyboards, review, and offline validators need no API key.
`short-drama-produce` is different: its Seedance, GPT Image 2, and MiniMax Music adapters can
spend real money. Never run `production_tool.py confirm` or `run` during setup or verification.
A real production task must show the exact prepared job and fingerprint, receive explicit user
confirmation for that exact preview, never start another attempt while one is `running`, and
require a fresh confirmation after any changed input or started failure. Keep adapter
configuration and credentials outside the project. See
`drama-skills/references/install-and-operations.md` and
`drama-skills/references/production-safety.md`.

## Step 6 — Runtime-specific shared-root checks


- `jeo`, `jeopi`, `opencode`, and `gjc` discover `~/.agents/skills` directly; no skills CLI agent ID is needed.
- GJC may require skill discovery to be enabled and `~/.agents/skills` added to its
  `skills.customDirectories`. Inspect its current config and merge only those keys; never
  replace the whole file.
- If an agent has no native skill loader, report that limitation rather than copying all
  skill folders into an unverified directory.
- Aside does not read `~/.agents/skills`. It loads account skills from
  `~/.aside/u/<accountId>/skills/user/`, populated by the Step 4 mirror. Re-run that mirror
  after any skill update, and never write into its sibling `builtin/`.

## Step 7 — Verify and report

```bash
HOME="$USER_HOME" skills list -g 2>/dev/null || HOME="$USER_HOME" npx --yes skills list --global
HOME="$USER_HOME" python3 "$SKILLS_ROOT/jeo-skill/scripts/jeo-skill.py" link
HOME="$USER_HOME" jeo-skill doctor
HOME="$USER_HOME" jeo-skill categories --json
command -v rtk >/dev/null 2>&1 && rtk gain
command -v semble >/dev/null 2>&1 && semble --help >/dev/null
command -v claude >/dev/null 2>&1 && claude mcp list
command -v codex >/dev/null 2>&1 && codex mcp list
command -v aside >/dev/null 2>&1 && aside --version
for acct in "$USER_HOME"/.aside/u/*/; do
  [ -d "$acct/skills/user" ] || continue
  printf 'aside %s: %s user skills\n' "$(basename "${acct%/}")" \
    "$(find "$acct/skills/user" -maxdepth 2 -name SKILL.md 2>/dev/null | wc -l | tr -d ' ')"
done
```

Finally report:

1. detected OS and agents;
2. selected mode and installed skill count;
3. exact global and per-agent paths used, including each Aside account's
   `skills/user/` path and how many skills were mirrored there;
4. MCP/shell/plugin registrations completed or skipped, with reasons — note whether Aside
   was registered as an MCP server, and that servers Aside consumes stay a manual UI step;
5. verification output and any manual follow-up;
6. in full mode, if `scrapingant-web-fetch` was not already configured, ask the user once
   whether to set it up now (sponsor skill, free 10,000 credits/month, no card) — see
   "ScrapingAnt MCP web fetch" below; do not set it up without an explicit yes.

Compare pre-existing skill names captured before installation with the final listing. A
successful run adds or updates jeo-skills targets and leaves every unrelated pre-existing
skill present. For Aside, that also means `skills/builtin/` is byte-identical and every
unrelated `skills/user/` entry is still there.

### Mex project memory scaffold (on demand)

The `mex` skill installs as documents plus `scripts/install.sh` (a real,
one-shot auto-installer) and `scripts/mex.sh` (read-only `doctor` +
`check`/`graph` wrappers). It never runs during blanket skill setup — prepare
it only when a task actually needs to scaffold a living wiki, detect drift,
or route architectural context to agents:

```bash
# 1. read-only environment report (Node.js, mex-agent binary vs. a same-named
#    collision like TeX Live's mex, Git repo, .mex/ scaffold, project anchor)
bash "$SKILLS_ROOT/mex/scripts/mex.sh" doctor /path/to/project

# 2. only after the user confirms the scaffold — one-shot, idempotent install:
#    registers the skill, installs mex-agent, runs `mex setup` (auto-answering
#    its tool-selection prompt via --tool, default codex/AGENTS.md so
#    jeo/gjc/jeopi pick it up), builds the code graph, and runs a drift check
bash "$SKILLS_ROOT/mex/scripts/install.sh" /path/to/project
```

`mex setup` only creates an empty `.mex/` scaffold plus a root anchor file
(`AGENTS.md`/`CLAUDE.md`/`.cursorrules`/etc., detected per tool) — that anchor
is the "rule document" jeo/gjc/jeopi/Claude Code/etc. auto-load, and
`install.sh` reports which one was written. It does **not** auto-populate the
wiki content; `install.sh` detects mex's own "COPY ABOVE THIS LINE" prompt and
warns that a human still has to paste it into a coding agent chat to fill in
`.mex/context/*.md` and `.mex/patterns/*` from the real codebase. mex's MCP
package is not published upstream as of this writing — do not claim an MCP
server got wired up for any agent. Never run `install.sh` as part of blanket
setup or verification; it stays a task-triggered, user-confirmed action. See
`mex/references/commands.md` for the full command reference.


### ScrapingAnt MCP web fetch (ask once in full mode, needs a key)

The `scrapingant-web-fetch` skill installs as documents plus
`scripts/scrapingant.sh` (`doctor` / `install` / `credits` / `probe`). It wraps
ScrapingAnt's **hosted** MCP server, so blanket setup must not silently register it —
the server needs a user-owned API key and every call spends that user's credits. In
full mode, once the rest of the install finishes, ask the user once (Step 7, report
item 6) whether they also want to set this up now: ScrapingAnt is a jeo-skills sponsor
with a generous free tier, so it is worth surfacing even though blanket setup never
auto-registers it. Outside full mode, or if the user declines, prepare it only when a
task actually needs live web content that a plain fetch cannot reach (Cloudflare/anti-bot,
JS-only pages, geo-restricted content):

```bash
# 1. read-only, offline report (key present? curl? client configs? already registered?)
bash "$SKILLS_ROOT/scrapingant-web-fetch/scripts/scrapingant.sh" doctor

# 2. only after the user supplies a key (free tier: 10,000 credits/month at signup,
#    no card — https://scrapingant.com?ref=ztewzmv&tm_source=readme)
export SCRAPINGANT_API_KEY="<user-provided-key>"
bash "$SKILLS_ROOT/scrapingant-web-fetch/scripts/scrapingant.sh" install claude-code
```

Registration is one `claude mcp add scrapingant --transport http
https://api.scrapingant.com/mcp -H "x-api-key: $SCRAPINGANT_API_KEY"`; every
other client (Claude Desktop, Cursor, Cline, Windsurf, VS Code/Copilot) takes a
config snippet from `install <client>` or `references/mcp-clients.md`. Never
write the key into a repo file or echo it — the scripts mask it and pass it to
curl over stdin. Credits are real money: static fetch costs 1 credit, JS
rendering 10, residential proxy 25/125, so escalate only after a cheaper attempt
fails, and check the remaining balance with `scrapingant.sh credits`. ScrapingAnt
sponsors jeo-skills; the signup link above is a referral link and the key always
stays with the user.