@bitmagic/cli 0.1.61 → 0.1.62-dev.0

package/dist/scaffold/reference-guidance.js

@@ -8,6 +8,7 @@
  * same as there — these strings land inside template literals ultimately emitted into scaffolded
  * markdown, so backticks are escaped exactly as project-files.ts escapes them.
  */
+import { PRIMARY_SKILLS_DIR } from './agent-targets.js';
 /** The `## Reference image` section of the scaffolded AGENTS.md, placed before the cover section. */
 export const AGENTS_MD_REFERENCE_SECTION = `## Reference image — offer it when the idea has a strong setting
 
@@ -27,7 +28,7 @@ style reference for \`generate skybox|background|block-type|image\`, \`bitmagic
 call as \`--reference-image <file>\` instead. Accepting prints a durable URL: paste it into
 \`GAME-DESIGN.md\`'s world/look section, since \`.bitmagic/\` is not committed and
 \`bitmagic reference accept <url>\` is how a fresh clone gets it back. Details are in
-\`.claude/skills/generating-assets/SKILL.md\`; skip the offer when the idea has no visual identity
+\`${PRIMARY_SKILLS_DIR}/generating-assets/SKILL.md\`; skip the offer when the idea has no visual identity
 yet.
 
 `;

package/dist/scaffold/reference-guidance.js.map

@@ -1 +1 @@
-{"version":3,"file":"reference-guidance.js","sourceRoot":"","sources":["../../src/scaffold/reference-guidance.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,qGAAqG;AACrG,MAAM,CAAC,MAAM,2BAA2B,GAAG;;;;;;;;;;;;;;;;;;;;;CAqB1C,CAAC;AAEF,2EAA2E;AAC3E,MAAM,CAAC,MAAM,8BAA8B,GAAG;;;;;;CAM7C,CAAC;AAEF,gGAAgG;AAChG,MAAM,CAAC,MAAM,8BAA8B,GAAG;;CAE7C,CAAC;AAEF,4EAA4E;AAC5E,MAAM,CAAC,MAAM,gCAAgC,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA8B/C,CAAC;AAEF,4EAA4E;AAC5E,MAAM,CAAC,MAAM,0BAA0B,GACrC,6HAA6H,CAAC"}
+{"version":3,"file":"reference-guidance.js","sourceRoot":"","sources":["../../src/scaffold/reference-guidance.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAExD,qGAAqG;AACrG,MAAM,CAAC,MAAM,2BAA2B,GAAG;;;;;;;;;;;;;;;;;;IAkBvC,kBAAkB;;;CAGrB,CAAC;AAEF,2EAA2E;AAC3E,MAAM,CAAC,MAAM,8BAA8B,GAAG;;;;;;CAM7C,CAAC;AAEF,gGAAgG;AAChG,MAAM,CAAC,MAAM,8BAA8B,GAAG;;CAE7C,CAAC;AAEF,4EAA4E;AAC5E,MAAM,CAAC,MAAM,gCAAgC,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA8B/C,CAAC;AAEF,4EAA4E;AAC5E,MAAM,CAAC,MAAM,0BAA0B,GACrC,6HAA6H,CAAC"}

package/dist/scaffold/skill-files.d.ts

@@ -6,15 +6,38 @@
  * those were 116 lines of loud facts riding in every request's context).
  *
  * Same contract as the renderers there: each is a pure function returning the file's contents,
- * registered in `PLATFORM_GENERATED_FILES` (project.ts) so `bitmagic init` writes it and
- * `bitmagic upgrade` refreshes it — the only path by which an existing project learns about a new
- * capability. `project-files.test.ts` enforces the frontmatter (name == directory) and that
- * AGENTS.md names every shipped skill. The same template-literal rule applies: the markdown is
- * full of backticks, so every one inside is escaped as \` and the test checks the rendered output.
+ * registered in `SHIPPED_SKILLS` (project.ts) so `bitmagic init` writes it and `bitmagic upgrade`
+ * refreshes it — the only path by which an existing project learns about a new capability.
+ * `project-files.test.ts` enforces the frontmatter (name == directory) and that AGENTS.md names
+ * every shipped skill. The same template-literal rule applies: the markdown is full of backticks,
+ * so every one inside is escaped as \` and the test checks the rendered output.
  */
-export declare function renderSkillsReadme(): string;
+import type { SkillRenderContext } from './project-files.js';
 /**
- * `.claude/skills/making-a-trailer/SKILL.md` — the whole trailer flow, and the craft that makes a
+ * `.kiro/steering/bitmagic.md` — Kiro's startup instructions, and the only per-agent extra file
+ * this scaffold writes besides Claude Code's.
+ *
+ * Kiro is the one supported agent that does not read the root `AGENTS.md` on its own: its
+ * convention is `.kiro/steering/*.md`, markdown loaded into context by an `inclusion` mode declared
+ * in YAML front matter that must start at byte zero (`inclusion: always` loads it into every
+ * interaction, and a file with no front matter at all is treated as always). That much is
+ * documented; what Kiro does with a root `AGENTS.md` is not, which is exactly why this file is a
+ * POINTER and not a second copy of the guidance. A copy would be another thing to keep current, and
+ * `agent-targets.ts` explains why nothing here may depend on an unverified integration point:
+ * worst case, Kiro ignores this file and its creator is no worse off than before it existed.
+ *
+ * The two commands are repeated rather than left to AGENTS.md because they are what a cold start
+ * gets wrong — an agent that has not yet opened AGENTS.md still needs `bitmagic dev` running and
+ * still needs to reload when it stops.
+ */
+export declare function renderKiroSteering(): string;
+/**
+ * The one shipped skill whose text is directory-specific, and so the one that reads its render
+ * context: it names the directory it is sitting in, and the sibling copies it is not.
+ */
+export declare function renderSkillsReadme({ skillsDir, skillDirs }: SkillRenderContext): string;
+/**
+ * `<skills dir>/making-a-trailer/SKILL.md` — the whole trailer flow, and the craft that makes a
  * cut watchable.
  *
  * Two kinds of knowledge live here on purpose. The FLOW (record → make → look → publish) is plain
@@ -25,7 +48,7 @@ export declare function renderSkillsReadme(): string;
  */
 export declare function renderTrailerSkill(): string;
 /**
- * `.claude/skills/publishing-a-game/SKILL.md` — the whole ship-it path, and every way it refuses.
+ * `<skills dir>/publishing-a-game/SKILL.md` — the whole ship-it path, and every way it refuses.
  *
  * This is the largest block that came out of AGENTS.md, and it is the clearest case for the split:
  * an agent about to publish KNOWS it is publishing, and an agent staring at a non-zero exit code
@@ -37,7 +60,7 @@ export declare function renderTrailerSkill(): string;
  */
 export declare function renderPublishingSkill(): string;
 /**
- * `.claude/skills/working-with-the-creator/SKILL.md` — the dev view as a two-way channel.
+ * `<skills dir>/working-with-the-creator/SKILL.md` — the dev view as a two-way channel.
  *
  * The creator is not only watching: they drag gizmos into `world.json`, they paste frames from
  * their running game, and one editor action (`hq.requested`) is a job handed to the agent. Reading

package/dist/scaffold/skill-files.js

@@ -6,23 +6,78 @@
  * those were 116 lines of loud facts riding in every request's context).
  *
  * Same contract as the renderers there: each is a pure function returning the file's contents,
- * registered in `PLATFORM_GENERATED_FILES` (project.ts) so `bitmagic init` writes it and
- * `bitmagic upgrade` refreshes it — the only path by which an existing project learns about a new
- * capability. `project-files.test.ts` enforces the frontmatter (name == directory) and that
- * AGENTS.md names every shipped skill. The same template-literal rule applies: the markdown is
- * full of backticks, so every one inside is escaped as \` and the test checks the rendered output.
+ * registered in `SHIPPED_SKILLS` (project.ts) so `bitmagic init` writes it and `bitmagic upgrade`
+ * refreshes it — the only path by which an existing project learns about a new capability.
+ * `project-files.test.ts` enforces the frontmatter (name == directory) and that AGENTS.md names
+ * every shipped skill. The same template-literal rule applies: the markdown is full of backticks,
+ * so every one inside is escaped as \` and the test checks the rendered output.
  */
-export function renderSkillsReadme() {
-    return `# Claude Code skills
+import { describeSkillsDir } from './agent-targets.js';
+/**
+ * `.kiro/steering/bitmagic.md` — Kiro's startup instructions, and the only per-agent extra file
+ * this scaffold writes besides Claude Code's.
+ *
+ * Kiro is the one supported agent that does not read the root `AGENTS.md` on its own: its
+ * convention is `.kiro/steering/*.md`, markdown loaded into context by an `inclusion` mode declared
+ * in YAML front matter that must start at byte zero (`inclusion: always` loads it into every
+ * interaction, and a file with no front matter at all is treated as always). That much is
+ * documented; what Kiro does with a root `AGENTS.md` is not, which is exactly why this file is a
+ * POINTER and not a second copy of the guidance. A copy would be another thing to keep current, and
+ * `agent-targets.ts` explains why nothing here may depend on an unverified integration point:
+ * worst case, Kiro ignores this file and its creator is no worse off than before it existed.
+ *
+ * The two commands are repeated rather than left to AGENTS.md because they are what a cold start
+ * gets wrong — an agent that has not yet opened AGENTS.md still needs `bitmagic dev` running and
+ * still needs to reload when it stops.
+ */
+export function renderKiroSteering() {
+    return `---
+inclusion: always
+---
+
+# Bitmagic
 
-Claude Code skills placed in this directory apply to this project. See \`AGENTS.md\` at the
-project root for the guidance an agent should read before editing this game.
+This is a Bitmagic game project.
 
+**Read \`AGENTS.md\` at the project root before editing anything here.** It describes this engine
+and this version of the GDK, \`bitmagic upgrade\` keeps it current, and it outranks anything you
+remember about Bitmagic. Your own copy of the skills it names is in \`.kiro/skills/\`.
+
+Two things it will tell you that are worth having before you have read it:
+
+- **Start \`bitmagic dev\` in the background and leave it running**, before you build anything. It
+  serves the game and the editor so the person you are building for can watch and steer.
+- **Run \`bitmagic reload\` when you finish a turn**, so their browser shows the finished work
+  rather than a frame from the middle of it. It exits 0 and does nothing when no dev server is up.
+`;
+}
+/**
+ * The one shipped skill whose text is directory-specific, and so the one that reads its render
+ * context: it names the directory it is sitting in, and the sibling copies it is not.
+ */
+export function renderSkillsReadme({ skillsDir, skillDirs }) {
+    // Built outside the literal because nesting a template literal inside `${}` of a file that
+    // escapes every backtick is the one place that escaping reliably goes wrong.
+    const siblings = skillDirs.filter((dir) => dir !== skillsDir).map((dir) => '`' + dir + '/`');
+    // A bullet list rather than a sentence: the directory names are substituted, so any sentence
+    // long enough to hold two of them wraps at a width this file cannot know.
+    const alsoWritten = siblings.length === 0
+        ? ''
+        : '\nAgents do not agree on where project skills live, so the shipped set below is written into' +
+            "\nevery directory this project's agents read — this one, and:\n\n" +
+            siblings.map((dir) => `- ${dir}`).join('\n') +
+            '\n\nThey hold the same guidance, and `bitmagic upgrade` refreshes every copy.\n';
+    return `# Agent skills for this Bitmagic game
+
+This directory is \`${skillsDir}/\` — ${describeSkillsDir(skillsDir)}.
+
+See \`AGENTS.md\` at the project root for the guidance an agent should read before editing this game.
+${alsoWritten}
 ## Which of these are yours
 
 \`planning-a-game/\`, \`finding-engine-apis/\`, \`generating-assets/\`, \`checking-usage/\`,
 \`judging-quality/\`, \`theming-the-hud/\`, \`making-a-trailer/\`, \`publishing-a-game/\`,
-\`working-with-the-creator/\` — and
+\`working-with-the-creator/\`, \`converting-unity-levels/\` — and
 this README — are shipped by the Bitmagic CLI and **re-rendered by \`bitmagic upgrade\`**. They
 describe what the CLI and the engine can do, so they have to stay current with both; edits to them
 are lost on the next upgrade.
@@ -38,14 +93,15 @@ are lost on the next upgrade.
 | \`making-a-trailer/\` | asked for a trailer, a highlight reel, a gameplay video, or to record gameplay — \`bitmagic trailer\` from recording to a CDN link, and how to tune the cut from prompts |
 | \`publishing-a-game/\` | shipping the game to bitmagic.ai — the verify gate, public vs private, thumbnails, category tags, and every way \`bitmagic publish\` can refuse |
 | \`working-with-the-creator/\` | they are editing alongside you — gizmo drags into \`world.json\`, a pasted frame from their game, \`.bitmagic/edit/events.jsonl\`, their phone |
+| \`converting-unity-levels/\` | a creator wants a Unity scene or game ported, replicated or "brought over" — reusing its prefabs, FBX models and colliders — or a converted level has pieces rotated, mis-scaled, walls that do not collide, an empty corner |
 
 Every other directory here is yours. \`upgrade\` never opens a skill it does not ship, and never
-deletes anything under \`.claude/\`. Put project-specific guidance in a skill of your own, or in
-\`AGENTS.md\` — both are left alone.
+deletes anything under a skills directory. Put project-specific guidance in a skill of your own, or
+in \`AGENTS.md\` — both are left alone.
 `;
 }
 /**
- * `.claude/skills/making-a-trailer/SKILL.md` — the whole trailer flow, and the craft that makes a
+ * `<skills dir>/making-a-trailer/SKILL.md` — the whole trailer flow, and the craft that makes a
  * cut watchable.
  *
  * Two kinds of knowledge live here on purpose. The FLOW (record → make → look → publish) is plain
@@ -208,7 +264,7 @@ from the changed region, compare with the previous \`-rN\`, deliver the URL.
 `;
 }
 /**
- * `.claude/skills/publishing-a-game/SKILL.md` — the whole ship-it path, and every way it refuses.
+ * `<skills dir>/publishing-a-game/SKILL.md` — the whole ship-it path, and every way it refuses.
  *
  * This is the largest block that came out of AGENTS.md, and it is the clearest case for the split:
  * an agent about to publish KNOWS it is publishing, and an agent staring at a non-zero exit code
@@ -332,7 +388,7 @@ blocked at the moment you ship.
 `;
 }
 /**
- * `.claude/skills/working-with-the-creator/SKILL.md` — the dev view as a two-way channel.
+ * `<skills dir>/working-with-the-creator/SKILL.md` — the dev view as a two-way channel.
  *
  * The creator is not only watching: they drag gizmos into `world.json`, they paste frames from
  * their running game, and one editor action (`hq.requested`) is a job handed to the agent. Reading

package/dist/scaffold/skill-files.js.map

@@ -1 +1 @@
-{"version":3,"file":"skill-files.js","sourceRoot":"","sources":["../../src/scaffold/skill-files.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,MAAM,UAAU,kBAAkB;IAChC,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA6BR,CAAC;AACF,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,kBAAkB;IAChC,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAsJR,CAAC;AACF,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,qBAAqB;IACnC,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA8GR,CAAC;AACF,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,+BAA+B;IAC7C,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAkER,CAAC;AACF,CAAC"}
+{"version":3,"file":"skill-files.js","sourceRoot":"","sources":["../../src/scaffold/skill-files.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAGvD;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,kBAAkB;IAChC,OAAO;;;;;;;;;;;;;;;;;;CAkBR,CAAC;AACF,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,kBAAkB,CAAC,EAAE,SAAS,EAAE,SAAS,EAAsB;IAC7E,2FAA2F;IAC3F,6EAA6E;IAC7E,MAAM,QAAQ,GAAG,SAAS,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,KAAK,SAAS,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,GAAG,GAAG,GAAG,IAAI,CAAC,CAAC;IAC7F,6FAA6F;IAC7F,0EAA0E;IAC1E,MAAM,WAAW,GACf,QAAQ,CAAC,MAAM,KAAK,CAAC;QACnB,CAAC,CAAC,EAAE;QACJ,CAAC,CAAC,8FAA8F;YAC9F,mEAAmE;YACnE,QAAQ,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,KAAK,GAAG,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC;YAC5C,iFAAiF,CAAC;IAExF,OAAO;;sBAEa,SAAS,SAAS,iBAAiB,CAAC,SAAS,CAAC;;;EAGlE,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;CA0BZ,CAAC;AACF,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,kBAAkB;IAChC,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAsJR,CAAC;AACF,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,qBAAqB;IACnC,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA8GR,CAAC;AACF,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,+BAA+B;IAC7C,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAkER,CAAC;AACF,CAAC"}

package/dist/scaffold/unity-skill-files.d.ts

@@ -0,0 +1,30 @@
+/**
+ * The `converting-unity-levels` skill: a Unity scene + prefabs + FBX + colliders into one GLB and
+ * collider data for a Bitmagic game. Distilled from a 2D arena-shooter port, where every rule in
+ * it was paid for with a level that looked plausible and was wrong.
+ *
+ * Same contract as `skill-files.ts`: pure functions returning file contents, registered in
+ * `SHIPPED_SKILLS` (project.ts), so every skills directory the project holds receives a copy. The
+ * skill is prose plus four references; the Python and Blender scripts it drives ship in the
+ * package's `assets/unity-import/` (see `files` in package.json) rather than being rendered into
+ * every project, since most games never port a Unity level and the scripts are large. Nothing
+ * game-specific is in those scripts: each project describes itself in `tools/unity-import.json`,
+ * which the skill's step 0 walks through.
+ *
+ * Scope, stated in the skill itself: the visual pipeline is general; collider extraction is
+ * general; the emitted level data is shaped for 2D-on-a-plane games, and a 3D game builds its
+ * physics from the raw collider JSON instead.
+ *
+ * Generated from the markdown in the origin project's `.claude/skills/converting-unity-levels/`;
+ * backticks and `${` are escaped for the template literal, and `project-files.test.ts` checks the
+ * rendered frontmatter.
+ */
+export declare function renderUnityLevelsSkill(): string;
+/** `<skills dir>/converting-unity-levels/references/unity-scene-traps.md` */
+export declare function renderUnityLevelsTrapsReference(): string;
+/** `<skills dir>/converting-unity-levels/references/fbx-conversion.md` */
+export declare function renderUnityLevelsFbxReference(): string;
+/** `<skills dir>/converting-unity-levels/references/physics-and-shadows.md` */
+export declare function renderUnityLevelsPhysicsReference(): string;
+/** `<skills dir>/converting-unity-levels/references/verification.md` */
+export declare function renderUnityLevelsVerificationReference(): string;