jgengine 0.8.1 → 0.8.3

package/dist/cli/index.js

@@ -9,28 +9,29 @@ import { runDoctor } from "../doctor.js";
 import { cliVersion, findUp, readPackageJson } from "../pkg.js";
 import { runSkills } from "../skills.js";
 const ENGINE_PACKAGES = ["core", "react", "shell", "ws", "sql", "convex", "node", "assets"];
-const HELP = `jgengine ${cliVersion()} — the JGengine command line
-Pure-TypeScript, genre-agnostic game engine SDK. Packages: ${ENGINE_PACKAGES.map((name) => `@jgengine/${name}`).join(", ")}.
+const HELP = `jgengine ${cliVersion()} — agent-side CLI for the JGengine TypeScript game SDK
+Packages: ${ENGINE_PACKAGES.map((name) => `@jgengine/${name}`).join(", ")}.
+docs: https://jgengine.com · source: https://github.com/Noisemaker111/jgengine
 
-usage: jgengine <command> [...args]
+HUMAN INTERFACE (what people say to you — not a shell they must run):
+  Make a game that ... with jgengine
 
-  create "<Game Name>"  scaffold a playable base — flat world, spawned player, HUD, verify test.
-                        folder becomes My-Game-Name; name lands in game.config / HUD / title.
-                        [--in-repo|--standalone] [--no-install] [--pm bun|npm|pnpm]
-  skills -p | -g        install agent skills (api, newgame, verify). -p this project (default), -g global
-  doctor [dir]          diagnose a game project: version skew, missing peers, unstyled-UI @source gaps, shape drift
-  llms [package]        print packaged API docs (llms.txt) for an installed @jgengine/* package — agent-ready context
-  assets [...]          delegate to the @jgengine/assets CLI: list, search, pull CC0 3D model packs
-  versions              show CLI + installed @jgengine/* versions
-  help                  this map
+AGENT RESPONSE (you run these; do not dump this as homework for the user):
+  npx jgengine create "Game Name"   # scaffold + install skills into the project
+  cd Game-Name
+  # concept pitch → questions → build (see jgengine-newgame)
 
-docs: https://jgengine.com · source: https://github.com/Noisemaker111/jgengine
+usage: jgengine <command> [...args]
 
-entry (any directory, no monorepo needed):
-  npx jgengine create "Solitaire"
-  cd Solitaire
-  npx jgengine skills -p          # or: npx jgengine skills -g  (once, for every project)
-  # then: make Solitaire with jgengine
+  create "<Game Name>"  scaffold playable base + install agent skills into the project
+                        folder My-Game-Name; name → game.config / HUD / title
+                        [--in-repo|--standalone] [--no-install] [--no-skills] [--pm bun|npm|pnpm]
+  skills -p | -g        re-install skills (recovery only — create already installs them)
+  doctor [dir]          diagnose version skew, missing peers, unstyled HUD, shape drift
+  llms [package]        print packaged API docs (llms.txt) — agent-ready
+  assets [...]          @jgengine/assets CLI: list, search, pull CC0 packs
+  versions              CLI + installed @jgengine/* versions
+  help                  this map
 `;
 function runVersions() {
     console.log(`jgengine ${cliVersion()}`);

package/dist/create.js

@@ -2,6 +2,7 @@ import { spawnSync } from "node:child_process";
 import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join, relative, resolve, sep } from "node:path";
 import { cliVersion, findWorkspaceRoot, flag, hasFlag, isEngineMonorepo } from "./pkg.js";
+import { installSkills } from "./skills.js";
 import { gameTemplate, parseCreateName } from "./templates.js";
 export function writeGame(targetDir, id, name, variant) {
     for (const file of gameTemplate({ id, name, variant, engineVersion: cliVersion() })) {
@@ -64,7 +65,7 @@ function isInsideDir(child, parent) {
 export function runCreate(argv) {
     const nameArg = positionalArg(argv);
     if (nameArg === undefined) {
-        console.error('usage: jgengine create "<Game Name>" [--in-repo|--standalone] [--no-install] [--pm bun|npm|pnpm]');
+        console.error('usage: jgengine create "<Game Name>" [--in-repo|--standalone] [--no-install] [--no-skills] [--pm bun|npm|pnpm]');
         return 1;
     }
     let displayName;
@@ -111,6 +112,7 @@ export function runCreate(argv) {
             console.log("\nnext steps:");
             console.log(`  bun install                     # from ${workspaceRoot}`);
             console.log(`  bun run games:${id}             # play it standalone`);
+            console.log(`  # agent: open the project and build ${displayName} (skills live in the monorepo)`);
             return 0;
         }
         let installed = false;
@@ -126,13 +128,19 @@ export function runCreate(argv) {
             if (!installed)
                 console.error(`warning: ${pm} install failed — run it manually in ${targetDir}`);
         }
+        if (!hasFlag(argv, "no-skills")) {
+            const skillsStatus = installSkills("project", targetDir);
+            if (skillsStatus !== 0) {
+                console.error("warning: skill install failed — agent can still use AGENTS.md; retry: npx jgengine skills -p");
+            }
+        }
         const cdHint = relative(process.cwd(), targetDir) || ".";
         console.log("\nnext steps:");
         console.log(`  cd ${cdHint}`);
         if (!installed)
             console.log("  bun install   # or npm install");
-        console.log("  bun dev                 # or npm run dev — flat world, spawned player, working HUD");
-        console.log("  npx jgengine skills -p  # agent skills in this project (-g for global)");
+        console.log("  bun dev       # playable base (flat world, player, HUD)");
+        console.log(`  # agent: make ${displayName} with jgengine  (skills already in the project)`);
         return 0;
     }
     catch (error) {

package/dist/skills.d.ts

@@ -1,4 +1,5 @@
 export declare const SKILLS_SOURCE = "Noisemaker111/jgengine";
+export declare const GAME_SKILLS: readonly ["jgengine-api", "jgengine-newgame", "jgengine-verify"];
 export type SkillsScope = "global" | "project";
 export declare function parseSkillsArgs(argv: string[]): {
     scope: SkillsScope;
@@ -6,4 +7,5 @@ export declare function parseSkillsArgs(argv: string[]): {
     error: string;
 };
 export declare function skillsInstallArgs(scope: SkillsScope): string[];
+export declare function installSkills(scope: SkillsScope, cwd?: string): number;
 export declare function runSkills(argv: string[]): number;

package/dist/skills.js

@@ -1,5 +1,6 @@
 import { spawnSync } from "node:child_process";
 export const SKILLS_SOURCE = "Noisemaker111/jgengine";
+export const GAME_SKILLS = ["jgengine-api", "jgengine-newgame", "jgengine-verify"];
 export function parseSkillsArgs(argv) {
     let scope = null;
     for (const arg of argv) {
@@ -24,42 +25,43 @@ export function parseSkillsArgs(argv) {
     return { scope: scope ?? "project" };
 }
 export function skillsInstallArgs(scope) {
-    const args = ["--yes", "skills", "add", SKILLS_SOURCE, "-y", "--all"];
+    const args = ["--yes", "skills", "add", SKILLS_SOURCE, "-y"];
+    for (const skill of GAME_SKILLS) {
+        args.push("-s", skill);
+    }
+    args.push("-a", "*");
     if (scope === "global")
         args.push("-g");
     return args;
 }
+export function installSkills(scope, cwd) {
+    const where = scope === "global" ? "globally" : "in this project";
+    console.log(`installing agent skills ${where}: ${GAME_SKILLS.join(", ")}…`);
+    const result = spawnSync("npx", skillsInstallArgs(scope), {
+        stdio: "inherit",
+        shell: process.platform === "win32",
+        cwd,
+    });
+    return result.status ?? 1;
+}
 export function runSkills(argv) {
     const parsed = parseSkillsArgs(argv);
     if ("error" in parsed) {
         if (parsed.error === "help") {
             console.log(`usage: jgengine skills (-g|--global | -p|--project)
 
-  -p, --project   install into this project (.claude/skills) — default
+  -p, --project   install into this project (default)
   -g, --global    install for your user (every project / agent session)
 
-Installs jgengine-api, jgengine-newgame, and jgengine-verify from ${SKILLS_SOURCE}.
+Installs ${GAME_SKILLS.join(", ")} from ${SKILLS_SOURCE}.
 
-entry:
-  npx jgengine create "Solitaire"
-  cd Solitaire
-  npx jgengine skills -p
-  # tell your agent: make Solitaire with jgengine
-
-  # or once for all projects:
-  npx jgengine skills -g
+People do not run this. Agents use it; create already installs project skills.
 `);
             return 0;
         }
         console.error(`error: ${parsed.error}`);
-        console.error('usage: jgengine skills (-g|--global | -p|--project)');
+        console.error("usage: jgengine skills (-g|--global | -p|--project)");
         return 1;
     }
-    const where = parsed.scope === "global" ? "globally" : "in this project";
-    console.log(`installing JGengine agent skills ${where} (jgengine-api, jgengine-newgame, jgengine-verify)…`);
-    const result = spawnSync("npx", skillsInstallArgs(parsed.scope), {
-        stdio: "inherit",
-        shell: process.platform === "win32",
-    });
-    return result.status ?? 1;
+    return installSkills(parsed.scope);
 }

package/dist/templates.js

@@ -344,21 +344,32 @@ describe("${id} world", () => {
   });
 });
 `;
-const agentsMd = (name, variant) => `# ${name} — agent notes
+const agentsMd = (name, variant) => `# ${name} — agent briefing
 
-This is a JGengine game (pure-TypeScript engine SDK, \`@jgengine/*\` on npm). Load context before writing code:
+You are in a **JGengine** game project. JGengine is a pure-TypeScript game engine SDK on npm (\`@jgengine/core\`, \`react\`, \`shell\`, …). Site: https://jgengine.com · source: https://github.com/Noisemaker111/jgengine
 
-- Engine API surface: \`npx jgengine llms core\` (any package name works) prints the packaged API docs.
-- Agent skills — API reference, phased game-build workflow, browserless verify gate: \`npx jgengine skills -p\` (this project) or \`-g\` (global).
-- Setup broken or UI unstyled: \`npx jgengine doctor\`.
+**How people use JGengine:** they say *Make a game that … with jgengine* to an agent. They do **not** start from a CLI tutorial. \`npx jgengine\` is for **you** (scaffold, skills, docs).
 
-Rules this project follows:
+## What to do when the user wants this game built
 
-- Shape: \`src/\` holds only \`game.config.ts\`, \`index.tsx\`, \`main.tsx\`, \`loop.ts\`, \`world.ts\`, \`index.css\`; every game-specific module, UI component, and test lives under \`src/game/\`.
-- \`game.config.ts\` is the single entry — \`defineGame({...})\` from \`@jgengine/shell/defineGame\`.
-- Scene and world changes are proven with \`summarizeEnvironment\` assertions in \`bun test src\` (see \`src/game/world.world.test.ts\`), never by screenshots as the inner loop.
-- HUD styling is Tailwind v4: the \`@source\` entries in \`src/index.css\` must cover \`@jgengine/react\` and \`@jgengine/shell\`${variant === "in-repo" ? " (engine source dirs in this monorepo)" : " (their dist dirs in node_modules)"}, or engine UI classes are silently not generated and the HUD renders unstyled.
-- \`onNewPlayer\` spawns the player entity with \`id === ctx.player.userId\`; \`onTick\`'s \`dt\` is game time, never wall-clock.
+1. Read skills if present: \`jgengine-newgame\` (workflow), \`jgengine-api\` (API), \`jgengine-verify\` (prove it works). They land under \`.agents/skills/\` or \`.claude/skills/\` when scaffolded via create.
+2. If skills are missing (your problem, not the user's): \`npx jgengine skills -p\` or use this file + \`npx jgengine llms core\`.
+3. **User-facing first reply is short** — game name, fantasy in 2–4 lines, POV (1st / 3rd / top-down / HUD-only), world kind, scale vibe. Ask a few tight questions (POV, world, multiplayer, how big). **Do not** dump file trees, catalog ids, keybind tables, or full phase plans to the user.
+4. Keep the full engineering plan (files, systems, budgets) internal. After they answer, scaffold is already here — build in phases, full game not a slice.
+
+## Engine loaders
+
+- API docs in the tarball: \`npx jgengine llms core\` (any package: react, shell, …)
+- Doctor: \`npx jgengine doctor\`
+- Dev: \`bun dev\` / \`npm run dev\`
+
+## Project rules
+
+- Shape: \`src/\` holds only \`game.config.ts\`, \`index.tsx\`, \`main.tsx\`, \`loop.ts\`, \`world.ts\`, \`index.css\`; everything else under \`src/game/\`.
+- Entry: \`defineGame({...})\` from \`@jgengine/shell/defineGame\` in \`game.config.ts\`.
+- Prove world content with \`summarizeEnvironment\` in \`bun test\` (\`src/game/world.world.test.ts\`), not screenshot loops.
+- Tailwind v4: \`@source\` in \`src/index.css\` must cover \`@jgengine/react\` and \`@jgengine/shell\`${variant === "in-repo" ? " (engine source under packages/)" : " (dist under node_modules)"}, or the HUD is silently unstyled.
+- Spawn player with \`id === ctx.player.userId\` in \`onNewPlayer\`; \`onTick\` \`dt\` is game time.
 `;
 export function gameTemplate(options) {
     const { id, name, variant, engineVersion } = options;

package/llms.txt

@@ -1,7 +1,7 @@
 # @jgengine/jgengine
-> The JGengine command line — scaffold a playable game, diagnose a broken setup, and load engine docs and agent skills into any project. Start with `npx jgengine create "My Game Name"`.
+> Agent-side CLI for JGengine. People build by telling an agent: Make a game that ... with jgengine. Agents use this CLI (create, skills, doctor, llms). Docs: https://jgengine.com
 
-Version: 0.8.1
+Version: 0.8.3
 License: AGPL-3.0-only
 Repository: https://github.com/Noisemaker111/jgengine
 Docs: https://jgengine.com
@@ -53,8 +53,10 @@ Imports use deep paths: `@jgengine/jgengine/<path>`.
 
 - parseSkillsArgs (function): function parseSkillsArgs(argv: string[]): { scope: SkillsScope } | { error: string }
 - skillsInstallArgs (function): function skillsInstallArgs(scope: SkillsScope): string[]
+- installSkills (function): function installSkills(scope: SkillsScope, cwd?: string): number
 - runSkills (function): function runSkills(argv: string[]): number
 - SKILLS_SOURCE (const): const SKILLS_SOURCE: "Noisemaker111/jgengine"
+- GAME_SKILLS (const): const GAME_SKILLS: readonly ["jgengine-api", "jgengine-newgame", "jgengine-verify"]
 - SkillsScope (type): type SkillsScope = "global" | "project"
 
 ### @jgengine/jgengine/templates
@@ -302,14 +304,14 @@ Exact import paths and export names — **do not invent paths**; every row below
 
 ## Getting started (new project)
 
-Fastest path — the `jgengine` CLI scaffolds the entire canonical shape below (harness, skeleton, stub game, verify test, AGENTS.md) as a booting game:
+**People** start with one sentence to an agent: `Make a game that … with jgengine`. They do not need the CLI.
+
+**Agents** scaffold with the CLI — harness, skeleton, stub game, verify test, AGENTS.md, skills:
 
 ```sh
-npx jgengine create "My Game Name"   # folder → My-Game-Name; name lands in game.config / HUD / title
-cd My-Game-Name
-npx jgengine skills -p               # agent skills here; use -g once for global
-bun dev
-npx jgengine doctor                  # later, if the setup drifts (version skew, unstyled HUD, shape strays)
+npx jgengine create "My Game Name"   # folder → My-Game-Name; skills install automatically
+cd My-Game-Name && bun dev
+npx jgengine doctor                  # later, if setup drifts (version skew, unstyled HUD, shape)
 ```
 
 Manual equivalent:

package/package.json

@@ -1,10 +1,20 @@
 {
   "name": "jgengine",
-  "version": "0.8.1",
-  "description": "The JGengine command line — scaffold a playable game, diagnose a broken setup, and load engine docs and agent skills into any project. Start with `npx jgengine create \"My Game Name\"`.",
+  "version": "0.8.3",
+  "description": "Agent-side CLI for JGengine. People build by telling an agent: Make a game that ... with jgengine. Agents use this CLI (create, skills, doctor, llms). Docs: https://jgengine.com",
+  "keywords": [
+    "game-engine",
+    "typescript",
+    "jgengine",
+    "cli",
+    "three.js",
+    "agent",
+    "scaffold"
+  ],
   "license": "AGPL-3.0-only",
   "type": "module",
   "sideEffects": false,
+  "homepage": "https://jgengine.com",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/Noisemaker111/jgengine.git",