spine-rigc 2.57.0 → 2.58.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spine-rigc",
-  "version": "2.57.0",
+  "version": "2.58.1",
   "description": "AI-authored 2D rigging and animation, verified before it is written. rigc compiles a rig spec into skeleton data in the Spine 4.3 format, gates it with named assertions held to a spine-core round trip's verdicts, and emits nothing that fails. Ships as an agent skill.",
   "type": "module",
   "bin": {

package/skills/rigc/SKILL.md

@@ -16,9 +16,14 @@ whole interface, and this skill only says which of them to open.
 
 📖 **A failure line ends with the command that prints its row of the guide** —
 ` (see rigc guide <RULE>)`. Run that command first, before reading anything else:
-it prints that rule's row of the shipped guide and nothing else, and `rigc guide §<n>`
-(and `§<n>.<m>`, `§<n>.<m>.<k>`)
-prints one section of `docs/AUTHORING.md` — a compile error points at `§5.1`.
+it prints that rule's row of the shipped guide and nothing else. `rigc guide §<n>`
+(and `§<n>.<m>`, `§<n>.<m>.<k>`) prints the section's heading, own prose and
+subsection index from `docs/AUTHORING.md`; add `--all` to include subsection
+bodies. A leaf prints its full text either way. Sizes describe full ledger spans;
+`--all` with a rule name is refused, exit 2. A compile error points at its stable
+`CE_` code row. `rigc guide §5.1.<k>` prints a numbered compile-error group of
+at most 30,000 UTF-8 bytes, and `rigc guide §5.1` prints the introduction and
+index within that same limit; only legacy uncoded library errors point at `§5.1`.
 
 ## Non-negotiables
 

package/skills/rigc-face/SKILL.md

@@ -14,9 +14,14 @@ it will not do for you.
 
 📖 **A failure line ends with the command that prints its row of the guide** —
 ` (see rigc guide <RULE>)`. Run that command first, before reading anything else:
-it prints that rule's row of the shipped guide and nothing else, and `rigc guide §<n>`
-(and `§<n>.<m>`, `§<n>.<m>.<k>`)
-prints one section of `docs/AUTHORING.md` — a compile error points at `§5.1`.
+it prints that rule's row of the shipped guide and nothing else. `rigc guide §<n>`
+(and `§<n>.<m>`, `§<n>.<m>.<k>`) prints the section's heading, own prose and
+subsection index from `docs/AUTHORING.md`; add `--all` to include subsection
+bodies. A leaf prints its full text either way. Sizes describe full ledger spans;
+`--all` with a rule name is refused, exit 2. A compile error points at its stable
+`CE_` code row. `rigc guide §5.1.<k>` prints a numbered compile-error group of
+at most 30,000 UTF-8 bytes, and `rigc guide §5.1` prints the introduction and
+index within that same limit; only legacy uncoded library errors point at `§5.1`.
 
 ## Non-negotiables
 

package/skills/rigc-ingest/SKILL.md

@@ -15,9 +15,14 @@ not do for you.
 
 📖 **A failure line ends with the command that prints its row of the guide** —
 ` (see rigc guide <RULE>)`. Run that command first, before reading anything else:
-it prints that rule's row of the shipped guide and nothing else, and `rigc guide §<n>`
-(and `§<n>.<m>`, `§<n>.<m>.<k>`)
-prints one section of `docs/AUTHORING.md` — a compile error points at `§5.1`.
+it prints that rule's row of the shipped guide and nothing else. `rigc guide §<n>`
+(and `§<n>.<m>`, `§<n>.<m>.<k>`) prints the section's heading, own prose and
+subsection index from `docs/AUTHORING.md`; add `--all` to include subsection
+bodies. A leaf prints its full text either way. Sizes describe full ledger spans;
+`--all` with a rule name is refused, exit 2. A compile error points at its stable
+`CE_` code row. `rigc guide §5.1.<k>` prints a numbered compile-error group of
+at most 30,000 UTF-8 bytes, and `rigc guide §5.1` prints the introduction and
+index within that same limit; only legacy uncoded library errors point at `§5.1`.
 
 ## Non-negotiables
 

package/skills/rigc-motion/SKILL.md

@@ -15,9 +15,14 @@ not do for you.
 
 📖 **A failure line ends with the command that prints its row of the guide** —
 ` (see rigc guide <RULE>)`. Run that command first, before reading anything else:
-it prints that rule's row of the shipped guide and nothing else, and `rigc guide §<n>`
-(and `§<n>.<m>`, `§<n>.<m>.<k>`)
-prints one section of `docs/AUTHORING.md` — a compile error points at `§5.1`.
+it prints that rule's row of the shipped guide and nothing else. `rigc guide §<n>`
+(and `§<n>.<m>`, `§<n>.<m>.<k>`) prints the section's heading, own prose and
+subsection index from `docs/AUTHORING.md`; add `--all` to include subsection
+bodies. A leaf prints its full text either way. Sizes describe full ledger spans;
+`--all` with a rule name is refused, exit 2. A compile error points at its stable
+`CE_` code row. `rigc guide §5.1.<k>` prints a numbered compile-error group of
+at most 30,000 UTF-8 bytes, and `rigc guide §5.1` prints the introduction and
+index within that same limit; only legacy uncoded library errors point at `§5.1`.
 
 ## Non-negotiables
 

package/skills/rigc-rigging/SKILL.md

@@ -14,9 +14,14 @@ will not do for you.
 
 📖 **A failure line ends with the command that prints its row of the guide** —
 ` (see rigc guide <RULE>)`. Run that command first, before reading anything else:
-it prints that rule's row of the shipped guide and nothing else, and `rigc guide §<n>`
-(and `§<n>.<m>`, `§<n>.<m>.<k>`)
-prints one section of `docs/AUTHORING.md` — a compile error points at `§5.1`.
+it prints that rule's row of the shipped guide and nothing else. `rigc guide §<n>`
+(and `§<n>.<m>`, `§<n>.<m>.<k>`) prints the section's heading, own prose and
+subsection index from `docs/AUTHORING.md`; add `--all` to include subsection
+bodies. A leaf prints its full text either way. Sizes describe full ledger spans;
+`--all` with a rule name is refused, exit 2. A compile error points at its stable
+`CE_` code row. `rigc guide §5.1.<k>` prints a numbered compile-error group of
+at most 30,000 UTF-8 bytes, and `rigc guide §5.1` prints the introduction and
+index within that same limit; only legacy uncoded library errors point at `§5.1`.
 
 ## Non-negotiables
 

package/src/atlas.ts

@@ -1998,7 +1998,7 @@ function packOnePageByFootprint(
       if (shapesMeet(shape, put.x, put.y, other.shape, other.x, other.y)) {
         throw new CompileError(
           `internal: the footprint pass placed a ${shape.width}x${shape.height} cell at ${put.x},${put.y} over ` +
-            `the footprint of the ${other.shape.width}x${other.shape.height} cell at ${other.x},${other.y}`,
+            `the footprint of the ${other.shape.width}x${other.shape.height} cell at ${other.x},${other.y}`, 'CE_ATLAS_INTERNAL_FOOTPRINT_OVERLAP',
         );
       }
     }
@@ -2313,7 +2313,7 @@ function layoutPack(
         // Unreachable: every cell was proven to fit an empty page above. Kept as
         // a named stop rather than an infinite loop if that ever stops holding.
         throw new CompileError(
-          `packing stalled with ${remaining.length} region(s) left and an empty ${maxEdge}x${maxEdge} page`,
+          `packing stalled with ${remaining.length} region(s) left and an empty ${maxEdge}x${maxEdge} page`, 'CE_ATLAS_PACKING_STALLED',
         );
       }
       // ⭐ Then the page is written at the smallest power-of-two pair that holds
@@ -2337,7 +2337,7 @@ function layoutPack(
       if (shrunk === null) {
         // Unreachable for the same reason as the stall above: these cells were
         // just placed on a maxEdge page.
-        throw new CompileError(`page ${pageIndex + 1} of the spill holds ${onPage.length} region(s) that no page fits`);
+        throw new CompileError(`page ${pageIndex + 1} of the spill holds ${onPage.length} region(s) that no page fits`, 'CE_ATLAS_SPILL_UNPACKABLE');
       }
       const onThisPage: Placement[] = [];
       shrunk.rects.forEach((rect, i) => {
@@ -2460,19 +2460,19 @@ export function packAtlas(inputs: PackInput[], opts: PackOptions = {}): PackResu
   const stem = opts.pageStem ?? 'skeleton';
   const pageEdges = opts.pageEdges ?? DEFAULT_PAGE_EDGES;
   if (!PAGE_EDGES.includes(pageEdges)) {
-    throw new CompileError(`--page-edges ${JSON.stringify(String(opts.pageEdges))}; known values: ${PAGE_EDGES.join(', ')}`);
+    throw new CompileError(`--page-edges ${JSON.stringify(String(opts.pageEdges))}; known values: ${PAGE_EDGES.join(', ')}`, 'CE_ATLAS_PAGE_EDGES_VALUE');
   }
   const shape = opts.shape ?? DEFAULT_PACK_SHAPE;
   if (!PACK_SHAPES.includes(shape)) {
-    throw new CompileError(`--pack-shape ${JSON.stringify(String(opts.shape))}; known values: ${PACK_SHAPES.join(', ')}`);
+    throw new CompileError(`--pack-shape ${JSON.stringify(String(opts.shape))}; known values: ${PACK_SHAPES.join(', ')}`, 'CE_ATLAS_PACK_SHAPE_VALUE');
   }
   if (!Number.isInteger(pageSize) || pageSize < 1) {
-    throw new CompileError(`--page-size must be a positive integer, got ${String(opts.pageSize)}`);
+    throw new CompileError(`--page-size must be a positive integer, got ${String(opts.pageSize)}`, 'CE_ATLAS_PAGE_SIZE_POSITIVE_INTEGER');
   }
   if (!Number.isInteger(padding) || padding < 0) {
-    throw new CompileError(`--padding must be a non-negative integer, got ${String(opts.padding)}`);
+    throw new CompileError(`--padding must be a non-negative integer, got ${String(opts.padding)}`, 'CE_ATLAS_PADDING_NONNEGATIVE_INTEGER');
   }
-  if (inputs.length === 0) throw new CompileError('nothing to pack: this compile emitted no images');
+  if (inputs.length === 0) throw new CompileError('nothing to pack: this compile emitted no images', 'CE_ATLAS_IMAGES_REQUIRED');
 
   const maxEdge = floorPowerOfTwo(pageSize);
 
@@ -2485,7 +2485,7 @@ export function packAtlas(inputs: PackInput[], opts: PackOptions = {}): PackResu
       `"${sorted[i].region}" is ${sorted[i].width}x${sorted[i].height} and with --padding ${padding} needs a ` +
         `${cells[i].w}x${cells[i].h} cell, which does not fit a ${maxEdge}x${maxEdge} page ` +
         `(${sorted[i].absPath}). Raise --page-size, lower --padding, or leave this build unpacked — a packer ` +
-        'cannot split one drawing across two pages.',
+        'cannot split one drawing across two pages.', 'CE_ATLAS_REGION_EXCEEDS_PAGE',
     );
   }
 
@@ -2542,7 +2542,7 @@ export function packAtlas(inputs: PackInput[], opts: PackOptions = {}): PackResu
         // two reads, or one of the two readers is wrong about it.
         throw new CompileError(
           `"${place.region}" measured ${input.width}x${input.height} from its PNG header and decodes to ` +
-            `${source.width}x${source.height} (${input.absPath})`,
+            `${source.width}x${source.height} (${input.absPath})`, 'CE_ATLAS_IMAGE_DIMENSIONS_CHANGED',
         );
       }
       extrudeCell(plate, source, place.x - padding, place.y - padding, padding);

package/src/cli/core_commands.ts

@@ -2017,27 +2017,28 @@ export function cmdSkills(flags: Record<string, string>, positional: string[]):
 // ---------------------------------------------------------------------------
 
 /**
- * `rigc guide <RULE>` / `rigc guide §<n>[.<m>]`: a slice of the `docs/AUTHORING.md`
+ * `rigc guide <RULE>` / `rigc guide §<n>[.<m>[.<k>]] [--all]`: a slice of the `docs/AUTHORING.md`
  * this package ships, read now — never a copy (`src/guide.ts` says why). A
  * finding code's table is read from the shipped document it lives in, and the
  * answer names that file.
  */
 export function cmdGuide(flags: Record<string, string>, positional: string[]): void {
-  const flagged = Object.keys(flags);
-  if (flagged.length > 0) throw new UsageError(`guide takes no flags, and ${flagged.map((f) => `--${f}`).join(', ')} was given — name one rule or one §section`);
+  const flagged = Object.keys(flags).filter((flag) => flag !== 'all');
+  if (flagged.length > 0) throw new UsageError(`guide takes only --all, and ${flagged.map((f) => `--${f}`).join(', ')} was given — name one rule or one §section`);
   if (positional.length !== 1) {
     throw new UsageError(
       positional.length === 0
-        ? 'guide takes one rule name — the one a failure line names before its colon — or one §<n> / §<n>.<m>'
+        ? 'guide takes one rule name — the one a failure line names before its colon — or one §<n> / §<n>.<m> / §<n>.<m>.<k>'
         : `guide takes one rule name or one §section, and ${positional.length} were given: ${positional.map((p) => JSON.stringify(p)).join(', ')}`,
     );
   }
+  if (flags.all !== undefined && !positional[0].startsWith('§')) throw new UsageError(`guide --all takes a §section, and ${JSON.stringify(positional[0])} is a rule name — omit --all to read its row`);
   const elsewhere: Record<string, string> = {};
   for (const table of GUIDE_RULE_TABLES_ELSEWHERE) {
     const path = join(PACKAGE_ROOT, table.file);
     if (existsSync(path)) elsewhere[table.file] = readFileSync(path, 'utf8');
   }
-  const answer = guideAnswer(positional[0], { guide: readFileSync(join(PACKAGE_ROOT, GUIDE_FILE), 'utf8'), elsewhere });
+  const answer = guideAnswer(positional[0], { guide: readFileSync(join(PACKAGE_ROOT, GUIDE_FILE), 'utf8'), elsewhere }, { all: flags.all !== undefined });
   if (!answer.ok) throw new GuideError(refusalLine(answer.rule, answer.detail));
   for (const line of answer.lines) console.log(line);
 }

package/src/cli/shared.ts

@@ -132,7 +132,7 @@ export { PACKAGE_ROOT, readPackageMeta, readVersion };
  * needs a value` (issue #328). `CLI10`/`CLI11` in `selftest.ts` now hold the two
  * halves together by reading `--help` rather than by naming a flag.
  */
-const BOOLEAN_FLAGS = new Set(['all-frames', 'all-bones', 'help', 'copy-images', 'again', 'pack', 'copy', 'geometry', 'folds', 'accept-skeleton-differences', 'keep-pages', 'dim']);
+const BOOLEAN_FLAGS = new Set(['all', 'all-frames', 'all-bones', 'help', 'copy-images', 'again', 'pack', 'copy', 'geometry', 'folds', 'accept-skeleton-differences', 'keep-pages', 'dim']);
 
 /**
  * The flags a command is allowed to spell more than once.
@@ -1164,6 +1164,7 @@ const FLAG_MEANINGS: Record<string, string> = {
   ballot: `the ballot the --record'd vote answers (default \`${DEFAULT_BALLOT}\`); its embedded manifest is what the vote is checked against`,
   ledger: `the append-only JSONL the vote lands in (default \`${DEFAULT_LEDGER}\`)`,
   again: 'record a second vote on a ballot the ledger already has; without it, a repeat is refused rather than doubled',
+  all: 'guide §section only: include its subsection bodies; without it, a section with subsections prints its heading, own prose and subsection index; a leaf prints its full text either way',
   dir:
     `the directory to install into, resolved against your working directory (default \`${DEFAULT_SKILLS_DIR}\`, the ` +
     'workspace directory Codex, Gemini CLI and Antigravity read skills from)',
@@ -1858,13 +1859,17 @@ export const COMMANDS: CommandDoc[] = [
     spineFormat: false,
     usage: [
       'rigc guide <RULE>             (the guide\'s row for the rule a failure line names — the line ends with this command)',
-      'rigc guide §<n> | §<n>.<m> | §<n>.<m>.<k>    (one section of docs/AUTHORING.md: "## <n>.", the m-th ### under it, the k-th #### under that)',
+      'rigc guide §<n> | §<n>.<m> | §<n>.<m>.<k> [--all]    (a section\'s own prose and subsection index; --all includes their bodies)',
     ],
-    flags: [],
+    flags: ['all'],
     notes: [
       'guide reads the docs/AUTHORING.md this command ships with, at the moment it runs, and',
       'prints a slice of it — the row(s) whose first cell names the rule, each under the',
-      'file, section and heading it sits in, or one section as it stands. An ingest finding',
+      'file, section and heading it sits in, or a section\'s heading, own prose and child index.',
+      '§<n> is ## <n>., §<n>.<m> the m-th ### under it, §<n>.<m>.<k> the k-th #### under that.',
+      '--all includes the subsection bodies; a leaf prints its full text either way. The',
+      'header and index sizes describe full ledger spans. --all with a rule is refused.',
+      'An ingest finding',
       'code\'s row lives in docs/INGEST.md\'s finding-code table, and its answer names that',
       'file. A name the guide does not have is refused with the nearest real names, exit 1.',
     ],
@@ -2956,8 +2961,8 @@ function refuse(err: unknown, command: string | undefined, USAGE: string, entry:
     process.exit(2);
   }
   if (err instanceof CompileError) {
-    // Ends with ` (see rigc guide §5.1)` (issue #1397): a compile error names no rule, so it points at the section.
-    console.error(compileErrorLine(err.message));
+    // The site's code points at its one AUTHORING row; uncoded library errors keep the legacy section.
+    console.error(compileErrorLine(err.message, err.code));
     // The drops the compile recorded before it stopped, in the same line the
     // green build prints (issue #671). They were reported from the compile
     // RESULT alone, so the run that failed BECAUSE a file was missing was the