@onceworlds/cli 0.5.1 → 0.5.2

package/dist/cli.js

@@ -1046,7 +1046,7 @@ function readZip(zip) {
 var INSTRUCTIONS = `Onceworlds hosts browser games with multiplayer, saves and accounts built in. These tools build a game on the user's account as drafts: the user plays every draft on their Create page and publishes it there. You never publish.
 
 How to work:
-1. read_guide once. It is the reference for the platform's SDK (window.onceworlds) and what a multiplayer game must handle (lobby, ready, reloads, a host leaving, phones).
+1. read_guide: it returns an outline of the platform guide (the SDK, window.onceworlds, and what a multiplayer game must handle: lobby, ready, reloads, a host leaving, phones). Read "Rules of the platform", "Multiplayer rooms", "Matches" and "Designing multiplayer" with read_guide section=... before building, and the rest as you need it.
 2. new_game starts a folder from a template (party: rounds with a lobby, the best start for most multiplayer games; starter: a small real-time game). Build the game in that folder: plain HTML, CSS and JavaScript, or a library from a CDN (jsdelivr, cdnjs). Keep onceworlds.json's name and description right.
 3. check, then deploy_preview after every meaningful change. The user sees each push on their Create page within seconds.
 4. game_status shows the errors the user's plays of your latest draft hit. Fix them and push again.
@@ -1056,8 +1056,8 @@ var TOOLS = [
   {
     name: "read_guide",
     title: "Read the Onceworlds guide",
-    description: 'The platform guide (AGENTS.md): the SDK, multiplayer rooms and matches, what to handle, how to design and ship a game. Read it before building. Pass `section` (part of a heading, like "Matches" or "Secrets") to get only that part.',
-    inputSchema: { type: "object", properties: { section: { type: "string", description: "Part of a heading to return only that section." } }, additionalProperties: false },
+    description: 'The platform guide (AGENTS.md, about 80 KB): the SDK, multiplayer rooms and matches, what to handle, how to design and ship a game. Without `section` it returns the outline with sizes and which parts to read first. Pass `section` (part of a heading, like "Matches" or "Secrets") to get that part, or "all" for the whole guide (about 20,000 tokens: some clients cut that off).',
+    inputSchema: { type: "object", properties: { section: { type: "string", description: 'Part of a heading to return only that section, or "all".' } }, additionalProperties: false },
     annotations: { readOnlyHint: true }
   },
   {
@@ -1236,7 +1236,8 @@ async function readGuide(host, section) {
   } catch {
     throw new ToolError(`Could not read the guide from ${host.api}/agents.md.`);
   }
-  if (!section) return guide;
+  if (section?.toLowerCase() === "all") return guide;
+  if (!section) return guideOutline(guide);
   const wanted = section.toLowerCase();
   const lines = guide.split("\n");
   const out = [];
@@ -1262,6 +1263,29 @@ async function readGuide(host, section) {
   }
   return out.join("\n");
 }
+function guideOutline(guide) {
+  const lines = guide.split("\n");
+  const parts = [];
+  let fenced = false;
+  for (const line of lines) {
+    if (line.startsWith("```")) fenced = !fenced;
+    const heading = !fenced ? /^(#{2,3})\s+(.*)$/.exec(line) : null;
+    if (heading) parts.push({ title: heading[2], level: heading[1].length, bytes: 0 });
+    else if (parts.length) parts[parts.length - 1].bytes += line.length + 1;
+  }
+  const sized = parts.map((part, i) => {
+    let bytes = part.bytes;
+    for (let j = i + 1; j < parts.length && parts[j].level > part.level; j++) bytes += parts[j].bytes;
+    return { ...part, bytes };
+  });
+  const kb = (n) => `${Math.max(1, Math.round(n / 1024))} KB`;
+  return [
+    `The Onceworlds guide is ${kb(guide.length)}. Read it in parts: call read_guide again with section set to part of a heading below.`,
+    'Read these before building: "Rules of the platform", "Multiplayer rooms", "Matches", "Designing multiplayer for this game", "Before you ship a multiplayer game". Use section "all" for everything at once (about 20,000 tokens; some clients cut that off).',
+    "",
+    ...sized.map((part) => `${part.level === 2 ? "" : "  "}- ${part.title} (${kb(part.bytes)})`)
+  ].join("\n");
+}
 async function newGame(host, args) {
   const slug = stringArg(args, "slug") ?? "";
   const name = (stringArg(args, "name") ?? "").trim();
@@ -1295,6 +1319,16 @@ async function newGame(host, args) {
   }
   await writeFile3(join3(dir, "onceworlds.json"), `${JSON.stringify({ slug, name, description, dir: "." }, null, 2)}
 `);
+  await writeFile3(
+    join3(dir, "README.md"),
+    `# ${name}
+
+${description ? `${description}
+
+` : ""}An Onceworlds game. Push drafts with the onceworlds tools (deploy_preview) and publish from ${host.api}/create/${slug}.
+The platform guide is AGENTS.md.
+`
+  );
   return [
     `Created ${dir} from the ${template} template (${written.join(", ")}, onceworlds.json).`,
     "",
@@ -1334,7 +1368,7 @@ function formatStatus(raw) {
 }
 
 // src/index.ts
-var CLI_VERSION = "0.5.1";
+var CLI_VERSION = "0.5.2";
 var PRODUCTION_API = "https://onceworlds.com";
 var LOCAL_API = "http://localhost:8787";
 var USAGE = `Usage:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onceworlds/cli",
-  "version": "0.5.1",
+  "version": "0.5.2",
   "description": "Deploy games to Onceworlds.",
   "homepage": "https://onceworlds.com",
   "type": "module",