jgengine 0.8.0 → 0.8.2

package/dist/cli/index.js

@@ -7,23 +7,28 @@ import { createRequire } from "node:module";
 import { runCreate } from "../create.js";
 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()} — pure-TypeScript game engine SDK + agent entry
+Packages: ${ENGINE_PACKAGES.map((name) => `@jgengine/${name}`).join(", ")}.
+docs: https://jgengine.com · source: https://github.com/Noisemaker111/jgengine
 
-usage: jgengine <command> [...args]
+ENTRY (agents: run this when the user says "use jgengine" / "make a game with npx jgengine"):
+  npx jgengine create "Game Name"
+  cd Game-Name
+  # skills install automatically · AGENTS.md briefs you · then build the game
 
-  create <dir>     scaffold a playable game — flat world, spawned player, HUD, verify test.
-                   [--name <display name>] [--in-repo|--standalone] [--no-install] [--pm bun|npm|pnpm]
-  doctor [dir]     diagnose a game project: version skew, missing peers, unstyled-UI @source gaps, shape drift
-  skills           install the JGengine agent skills (API reference, game-build workflow, verify gate) into .claude/skills
-  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
+usage: jgengine <command> [...args]
 
-docs: https://jgengine.com · source: https://github.com/Noisemaker111/jgengine
-new here (human or agent)? run: npx jgengine create my-game && cd my-game && npx jgengine skills
+  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 only if create was run with --no-skills
+  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()}`);
@@ -61,14 +66,6 @@ function runLlms(argv) {
     process.stdout.write(readFileSync(join(found, "node_modules", packageName, "llms.txt"), "utf8"));
     return 0;
 }
-function runSkills() {
-    console.log("installing JGengine agent skills (jgengine-api, jgengine-newgame, jgengine-verify)…");
-    const result = spawnSync("npx", ["--yes", "skills", "add", "Noisemaker111/jgengine"], {
-        stdio: "inherit",
-        shell: process.platform === "win32",
-    });
-    return result.status ?? 1;
-}
 function runAssets(argv) {
     const require = createRequire(import.meta.url);
     let cliPath;
@@ -91,7 +88,7 @@ switch (command) {
         process.exit(runDoctor(rest));
         break;
     case "skills":
-        process.exit(runSkills());
+        process.exit(runSkills(rest));
         break;
     case "llms":
         process.exit(runLlms(rest));

package/dist/create.d.ts

@@ -1,4 +1,4 @@
 import { type TemplateVariant } from "./templates.js";
 export declare function writeGame(targetDir: string, id: string, name: string, variant: TemplateVariant): void;
-export declare function registerRootGameScript(rootDir: string, id: string): boolean;
+export declare function registerRootGameScript(rootDir: string, id: string, folderName?: string): boolean;
 export declare function runCreate(argv: string[]): number;

package/dist/create.js

@@ -1,8 +1,9 @@
 import { spawnSync } from "node:child_process";
 import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
-import { basename, dirname, join, relative, resolve } from "node:path";
+import { dirname, join, relative, resolve, sep } from "node:path";
 import { cliVersion, findWorkspaceRoot, flag, hasFlag, isEngineMonorepo } from "./pkg.js";
-import { displayNameFromId, GAME_ID_PATTERN, gameTemplate } from "./templates.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() })) {
         const dest = join(targetDir, file.path);
@@ -10,7 +11,7 @@ export function writeGame(targetDir, id, name, variant) {
         writeFileSync(dest, file.contents);
     }
 }
-export function registerRootGameScript(rootDir, id) {
+export function registerRootGameScript(rootDir, id, folderName = id) {
     const rootPackagePath = join(rootDir, "package.json");
     const root = JSON.parse(readFileSync(rootPackagePath, "utf8"));
     const scripts = root.scripts ?? {};
@@ -20,7 +21,7 @@ export function registerRootGameScript(rootDir, id) {
     const entries = Object.entries(scripts);
     const games = entries.filter(([k]) => k.startsWith("games:"));
     const rest = entries.filter(([k]) => !k.startsWith("games:"));
-    games.push([key, `bun run --cwd Games/${id} dev`]);
+    games.push([key, `bun run --cwd Games/${folderName} dev`]);
     games.sort(([a], [b]) => a.localeCompare(b));
     root.scripts = Object.fromEntries([...rest, ...games]);
     writeFileSync(rootPackagePath, `${JSON.stringify(root, null, 2)}\n`);
@@ -32,7 +33,7 @@ function pickPackageManager(preferred) {
     const probe = spawnSync("bun", ["--version"], { stdio: "ignore", shell: process.platform === "win32" });
     return probe.status === 0 ? "bun" : "npm";
 }
-const VALUE_FLAGS = new Set(["--name", "--pm"]);
+const VALUE_FLAGS = new Set(["--pm"]);
 function positionalArg(argv) {
     for (let index = 0; index < argv.length; index += 1) {
         const arg = argv[index];
@@ -45,67 +46,105 @@ function positionalArg(argv) {
     }
     return undefined;
 }
+function splitCreateArg(arg) {
+    const normalized = arg.replace(/\\/g, "/").replace(/\/+/g, "/");
+    const trimmed = normalized.replace(/\/$/, "");
+    const slash = trimmed.lastIndexOf("/");
+    if (slash < 0)
+        return { parentHint: null, titlePart: trimmed };
+    return {
+        parentHint: trimmed.slice(0, slash) || ".",
+        titlePart: trimmed.slice(slash + 1),
+    };
+}
+function isInsideDir(child, parent) {
+    const resolvedChild = resolve(child);
+    const resolvedParent = resolve(parent);
+    return resolvedChild === resolvedParent || resolvedChild.startsWith(resolvedParent + sep);
+}
 export function runCreate(argv) {
-    const dirArg = positionalArg(argv);
-    if (dirArg === undefined) {
-        console.error("usage: jgengine create <dir> [--name <display name>] [--in-repo|--standalone] [--no-install] [--pm bun|npm|pnpm]");
-        return 1;
-    }
-    const targetDir = resolve(dirArg);
-    const id = basename(targetDir);
-    if (!GAME_ID_PATTERN.test(id)) {
-        console.error(`error: directory name "${id}" must be kebab-case (lowercase letters, digits, dashes, starting with a letter)`);
-        return 1;
-    }
-    if (existsSync(targetDir) && readdirSync(targetDir).length > 0) {
-        console.error(`error: ${targetDir} already exists and is not empty`);
-        return 1;
-    }
-    const workspaceRoot = findWorkspaceRoot(dirname(targetDir));
-    const insideEngineRepo = workspaceRoot !== null && isEngineMonorepo(workspaceRoot);
-    const variant = hasFlag(argv, "standalone")
-        ? "standalone"
-        : hasFlag(argv, "in-repo") || insideEngineRepo
-            ? "in-repo"
-            : "standalone";
-    if (variant === "in-repo" && !insideEngineRepo) {
-        console.error("error: --in-repo requires the target to live under Games/ inside the jgengine engine monorepo");
+    const nameArg = positionalArg(argv);
+    if (nameArg === undefined) {
+        console.error('usage: jgengine create "<Game Name>" [--in-repo|--standalone] [--no-install] [--no-skills] [--pm bun|npm|pnpm]');
         return 1;
     }
-    const name = flag(argv, "name") ?? displayNameFromId(id);
-    writeGame(targetDir, id, name, variant);
-    console.log(`created ${name} (${variant}) with ${gameTemplateFileCount()} files in ${targetDir}`);
-    if (variant === "in-repo" && workspaceRoot !== null) {
-        if (registerRootGameScript(workspaceRoot, id)) {
-            console.log(`registered root script "games:${id}" in ${join(workspaceRoot, "package.json")}`);
+    let displayName;
+    let folderName;
+    let id;
+    try {
+        const { parentHint, titlePart } = splitCreateArg(nameArg);
+        ({ displayName, folderName, id } = parseCreateName(titlePart));
+        let parentDir = parentHint !== null ? resolve(parentHint) : process.cwd();
+        let targetDir = join(parentDir, folderName);
+        const workspaceRoot = findWorkspaceRoot(dirname(targetDir)) ?? findWorkspaceRoot(parentDir) ?? findWorkspaceRoot(process.cwd());
+        const insideEngineRepo = workspaceRoot !== null && isEngineMonorepo(workspaceRoot);
+        const variant = hasFlag(argv, "standalone")
+            ? "standalone"
+            : hasFlag(argv, "in-repo") || insideEngineRepo
+                ? "in-repo"
+                : "standalone";
+        if (variant === "in-repo") {
+            if (!insideEngineRepo || workspaceRoot === null) {
+                console.error("error: --in-repo requires the jgengine engine monorepo (packages/core + Games/)");
+                return 1;
+            }
+            if (parentHint === null) {
+                parentDir = join(workspaceRoot, "Games");
+                targetDir = join(parentDir, folderName);
+            }
+            const gamesDir = join(workspaceRoot, "Games");
+            if (!isInsideDir(targetDir, gamesDir)) {
+                console.error(`error: in-repo games must live under Games/ (got ${targetDir}; expected under ${gamesDir})`);
+                return 1;
+            }
         }
+        if (existsSync(targetDir) && readdirSync(targetDir).length > 0) {
+            console.error(`error: ${targetDir} already exists and is not empty`);
+            return 1;
+        }
+        writeGame(targetDir, id, displayName, variant);
+        console.log(`created ${displayName} (${variant}) → ${targetDir}`);
+        console.log(`  folder ${folderName}  package ${id}  name "${displayName}"`);
+        if (variant === "in-repo" && workspaceRoot !== null) {
+            if (registerRootGameScript(workspaceRoot, id, folderName)) {
+                console.log(`registered root script "games:${id}" in ${join(workspaceRoot, "package.json")}`);
+            }
+            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;
+        if (!hasFlag(argv, "no-install")) {
+            const pm = pickPackageManager(flag(argv, "pm"));
+            console.log(`installing dependencies with ${pm}…`);
+            const install = spawnSync(pm, ["install"], {
+                cwd: targetDir,
+                stdio: "inherit",
+                shell: process.platform === "win32",
+            });
+            installed = install.status === 0;
+            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(`  bun install                     # from ${workspaceRoot}`);
-        console.log(`  bun run games:${id}             # play it standalone`);
+        console.log(`  cd ${cdHint}`);
+        if (!installed)
+            console.log("  bun install   # or npm install");
+        console.log("  bun dev       # playable base (flat world, player, HUD)");
+        console.log(`  # agent: make ${displayName} with jgengine  (skills already in the project)`);
         return 0;
     }
-    let installed = false;
-    if (!hasFlag(argv, "no-install")) {
-        const pm = pickPackageManager(flag(argv, "pm"));
-        console.log(`installing dependencies with ${pm}…`);
-        const install = spawnSync(pm, ["install"], {
-            cwd: targetDir,
-            stdio: "inherit",
-            shell: process.platform === "win32",
-        });
-        installed = install.status === 0;
-        if (!installed)
-            console.error(`warning: ${pm} install failed — run it manually in ${targetDir}`);
+    catch (error) {
+        console.error(`error: ${error instanceof Error ? error.message : String(error)}`);
+        return 1;
     }
-    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   # install the JGengine agent skills for AI-assisted building");
-    return 0;
-}
-function gameTemplateFileCount() {
-    return gameTemplate({ id: "probe", name: "Probe", variant: "standalone", engineVersion: "0.0.0" }).length;
 }

package/dist/skills.d.ts

@@ -0,0 +1,11 @@
+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;
+} | {
+    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

@@ -0,0 +1,67 @@
+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) {
+        if (arg === "-g" || arg === "--global") {
+            if (scope === "project")
+                return { error: "use either -g/--global or -p/--project, not both" };
+            scope = "global";
+            continue;
+        }
+        if (arg === "-p" || arg === "--project") {
+            if (scope === "global")
+                return { error: "use either -g/--global or -p/--project, not both" };
+            scope = "project";
+            continue;
+        }
+        if (arg === "-y" || arg === "--yes")
+            continue;
+        if (arg === "-h" || arg === "--help")
+            return { error: "help" };
+        return { error: `unknown skills option: ${arg}` };
+    }
+    return { scope: scope ?? "project" };
+}
+export function skillsInstallArgs(scope) {
+    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 (default)
+  -g, --global    install for your user (every project / agent session)
+
+Installs ${GAME_SKILLS.join(", ")} from ${SKILLS_SOURCE}.
+
+create already installs project skills for you — you usually never need this command.
+`);
+            return 0;
+        }
+        console.error(`error: ${parsed.error}`);
+        console.error("usage: jgengine skills (-g|--global | -p|--project)");
+        return 1;
+    }
+    return installSkills(parsed.scope);
+}

package/dist/templates.d.ts

@@ -10,6 +10,15 @@ export interface TemplateFile {
     contents: string;
 }
 export declare const GAME_ID_PATTERN: RegExp;
+export declare const FOLDER_NAME_PATTERN: RegExp;
 export declare function displayNameFromId(id: string): string;
+export declare function displayNameFromInput(input: string): string;
+export declare function folderNameFromTitle(input: string): string;
+export declare function packageIdFromFolder(folder: string): string;
+export declare function parseCreateName(input: string): {
+    displayName: string;
+    folderName: string;
+    id: string;
+};
 export declare const IN_REPO_TSCONFIG_PATHS: Record<string, string[]>;
 export declare function gameTemplate(options: TemplateOptions): TemplateFile[];

package/dist/templates.js

@@ -1,10 +1,58 @@
 export const GAME_ID_PATTERN = /^[a-z][a-z0-9-]*$/;
+export const FOLDER_NAME_PATTERN = /^[A-Za-z][A-Za-z0-9-]*$/;
 export function displayNameFromId(id) {
     return id
         .split("-")
+        .filter((word) => word.length > 0)
         .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
         .join(" ");
 }
+export function displayNameFromInput(input) {
+    const trimmed = input.trim().replace(/\s+/g, " ");
+    if (trimmed.length === 0) {
+        throw new Error("game name must not be empty");
+    }
+    if (/\s/.test(trimmed))
+        return trimmed;
+    if (trimmed.includes("-"))
+        return displayNameFromId(trimmed.toLowerCase());
+    return trimmed.charAt(0).toUpperCase() + trimmed.slice(1);
+}
+export function folderNameFromTitle(input) {
+    const cleaned = input
+        .trim()
+        .replace(/[<>:"/\\|?*\u0000-\u001f]/g, "")
+        .replace(/\s+/g, " ");
+    if (cleaned.length === 0) {
+        throw new Error("game name must not be empty");
+    }
+    const folder = cleaned
+        .split(" ")
+        .filter((part) => part.length > 0)
+        .join("-")
+        .replace(/-+/g, "-")
+        .replace(/^-+|-+$/g, "");
+    if (!FOLDER_NAME_PATTERN.test(folder)) {
+        throw new Error(`folder name "${folder}" must start with a letter and contain only letters, digits, and dashes`);
+    }
+    return folder;
+}
+export function packageIdFromFolder(folder) {
+    const id = folder
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+    if (!GAME_ID_PATTERN.test(id)) {
+        throw new Error(`package id "${id}" must be kebab-case: lowercase letters, digits, dashes, starting with a letter`);
+    }
+    return id;
+}
+export function parseCreateName(input) {
+    const displayName = displayNameFromInput(input);
+    const folderName = folderNameFromTitle(input);
+    const id = packageIdFromFolder(folderName);
+    return { displayName, folderName, id };
+}
 const indexHtml = (name) => `<!doctype html>
 <html lang="en">
   <head>
@@ -296,21 +344,30 @@ describe("${id} world", () => {
   });
 });
 `;
-const agentsMd = (name, variant) => `# ${name} — agent notes
+const agentsMd = (name, variant) => `# ${name} — agent briefing
+
+You are in a **JGengine** game project. JGengine is a pure-TypeScript game engine SDK on npm (\`@jgengine/core\`, \`react\`, \`shell\`, …). The CLI is \`npx jgengine\`. Site: https://jgengine.com · source: https://github.com/Noisemaker111/jgengine
+
+## What to do when the user wants this game built
+
+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 \`npx jgengine create\`.
+2. If skills are missing: \`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.
 
-This is a JGengine game (pure-TypeScript engine SDK, \`@jgengine/*\` on npm). Load context before writing code:
+## Engine loaders
 
-- 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\` installs them into \`.claude/skills\`.
-- Setup broken or UI unstyled: \`npx jgengine doctor\`.
+- API docs in the tarball: \`npx jgengine llms core\` (any package: react, shell, …)
+- Doctor: \`npx jgengine doctor\`
+- Dev: \`bun dev\` / \`npm run dev\`
 
-Rules this project follows:
+## Project rules
 
-- 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.
+- 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 <dir>`.
+> JGengine CLI — pure-TypeScript game engine entry for humans and agents. Run: npx jgengine create "My Game Name" (scaffolds a playable base and installs agent skills). Then build the game. Docs: https://jgengine.com
 
-Version: 0.8.0
+Version: 0.8.2
 License: AGPL-3.0-only
 Repository: https://github.com/Noisemaker111/jgengine
 Docs: https://jgengine.com
@@ -12,7 +12,7 @@ Imports use deep paths: `@jgengine/jgengine/<path>`.
 ### @jgengine/jgengine/create
 
 - writeGame (function): function writeGame(targetDir: string, id: string, name: string, variant: TemplateVariant): void
-- registerRootGameScript (function): function registerRootGameScript(rootDir: string, id: string): boolean
+- registerRootGameScript (function): function registerRootGameScript(rootDir: string, id: string, folderName: string = id): boolean
 - runCreate (function): function runCreate(argv: string[]): number
 
 ### @jgengine/jgengine/doctor
@@ -32,7 +32,7 @@ Imports use deep paths: `@jgengine/jgengine/<path>`.
 - TemplateVariant (type): type TemplateVariant = "standalone" | "in-repo"
 - runCreate (function): function runCreate(argv: string[]): number
 - writeGame (function): function writeGame(targetDir: string, id: string, name: string, variant: TemplateVariant): void
-- registerRootGameScript (function): function registerRootGameScript(rootDir: string, id: string): boolean
+- registerRootGameScript (function): function registerRootGameScript(rootDir: string, id: string, folderName: string = id): boolean
 - diagnose (function): function diagnose(dir: string): Finding[]
 - runDoctor (function): function runDoctor(argv: string[]): number
 - Finding (interface): interface Finding
@@ -49,14 +49,29 @@ Imports use deep paths: `@jgengine/jgengine/<path>`.
 - hasFlag (function): function hasFlag(argv: string[], name: string): boolean
 - PackageJson (interface): interface PackageJson
 
+### @jgengine/jgengine/skills
+
+- 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
 
 - displayNameFromId (function): function displayNameFromId(id: string): string
+- displayNameFromInput (function): function displayNameFromInput(input: string): string
+- folderNameFromTitle (function): function folderNameFromTitle(input: string): string
+- packageIdFromFolder (function): function packageIdFromFolder(folder: string): string
+- parseCreateName (function): function parseCreateName(input: string): { displayName: string; folderName: string; id: string }
 - gameTemplate (function): function gameTemplate(options: TemplateOptions): TemplateFile[]
 - TemplateVariant (type): type TemplateVariant = "standalone" | "in-repo"
 - TemplateOptions (interface): interface TemplateOptions
 - TemplateFile (interface): interface TemplateFile
 - GAME_ID_PATTERN (const): const GAME_ID_PATTERN: RegExp
+- FOLDER_NAME_PATTERN (const): const FOLDER_NAME_PATTERN: RegExp
 - IN_REPO_TSCONFIG_PATHS (const): const IN_REPO_TSCONFIG_PATHS: Record<string, string[]>
 
 ## Guides
@@ -292,8 +307,9 @@ Exact import paths and export names — **do not invent paths**; every row below
 Fastest path — the `jgengine` CLI scaffolds the entire canonical shape below (harness, skeleton, stub game, verify test, AGENTS.md) as a booting game:
 
 ```sh
-npx jgengine create my-game   # then: cd my-game && 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.0",
-  "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 <dir>`.",
+  "version": "0.8.2",
+  "description": "JGengine CLI — pure-TypeScript game engine entry for humans and agents. Run: npx jgengine create \"My Game Name\" (scaffolds a playable base and installs agent skills). Then build the game. 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",