spine-rigc 2.58.0 → 2.58.1

package/README.md

@@ -612,7 +612,7 @@ commands take it and what its default is.
 | `bonedist --candidate … --reference … --bones …` | per-frame, per-bone world-transform distance against another skeleton — the ladder's stage 3, run on its own. `--bones <correspondence.json \| identity>` is required rather than defaulted: a candidate is entitled to its own bone names, so the pairing is stated |
 | `check --candidate <dir> --frames <dir> [--out <dir>]` | the candidate against reference pictures — the only instrument here that can see a *wrong animation*. `--out` also writes, for every frame the table lists, the picture its figures came from: reference, candidate, difference and overlay at native size |
 | `bench <rung> --candidate <dir>` | one rung of the benchmark ladder |
-| `guide <RULE>` / `guide §<n>[.<m>[.<k>]]` | the guide's row for the rule a failure line names — every `FAIL` line, `vote --record` refusal and `ingest` finding ends with ` (see rigc guide <RULE>)`, and a compile error with ` (see rigc guide §5.1)` — or one section of `docs/AUTHORING.md`, read from the installed file when it runs. A name it does not have is refused with the nearest real ones, exit 1 |
+| `guide <RULE>` / `guide §<n>[.<m>[.<k>]] [--all]` | the guide's row for the rule a failure line names — every `FAIL` line, `vote --record` refusal, `ingest` finding and coded compile error ends with ` (see rigc guide <RULE>)`; only legacy uncoded library errors point at `§5.1` — or a section's heading, own prose and subsection index, read from the installed `docs/AUTHORING.md` when it runs. `--all` includes the subsection bodies; a leaf prints its full text either way. Sizes describe full ledger spans. `--all` with a rule is refused, exit 2; an unknown name is refused with the nearest real ones, exit 1 |
 | `skills install [--dir …] [--copy]` | links every agent skill the package ships into `.agents/skills` (or `--dir`) as relative symlinks, or copies them with `--copy` — where Codex, Gemini CLI and Antigravity look. A second run has nothing to do; an entry already there that is not this command's is refused by name and nothing is written |
 
 `diff`, `bonedist`, `check` and `bench` measure against something you were given; the

package/docs/AUTHORING.md

@@ -296,7 +296,8 @@ for `vote` (default `ballot.html`).
 
 `guide` reads this page rather than a rig: `rigc guide <RULE>` prints the row of §5
 (or of `docs/INGEST.md`'s finding-code table) for the rule a failure line names, and
-`rigc guide §<n>` one section — §5 says when to reach for it.
+`rigc guide §<n>` its heading, own prose and subsection index; `--all` also prints
+the subsections' bodies. A leaf prints its full text either way — §5 says when to reach for it.
 
 `skills install` is the other command that is not about a rig: it puts the agent
 skills the package ships where an agent host looks for them. Run it through the
@@ -6787,14 +6788,18 @@ Failures arrive in two layers, and they read differently.
 ` (see rigc guide <RULE>)` — a gate's `FAIL` line, a `vote --record` refusal and an
 `ingest` finding. `rigc guide <RULE>` prints that rule's row(s), each under the file,
 the section and the heading it sits in, read from the shipped guide when it runs;
-`rigc guide §<n>` prints one section of this page and lists its subsections with their
-sizes, `rigc guide §<n>.<m>` the m-th `###` under it and `rigc guide §<n>.<m>.<k>` the
-k-th `####` under that — so a citation such as §4.5.1 here is a command. A name the
+`rigc guide §<n>` prints the section's heading, its own prose and an index of its
+subsections with their sizes. `rigc guide §<n> --all` also prints those subsections'
+bodies; a section without subsections prints its full text either way. The header
+and index sizes describe the full spans in this ledger, including subsection bodies.
+`rigc guide §<n>.<m>` addresses the m-th `###` under it and `rigc guide §<n>.<m>.<k>` the
+k-th `####` under that; both take `--all` too — so a citation such as §4.5.1 here is a command. A name the
 guide does not have is refused by a rule of its own — `GUIDE_RULE_KNOWN` with the
 three nearest real names, `GUIDE_SECTION_KNOWN` with the sections that do exist —
-on stderr, exit 1 (§5.5). A compile error
-names no rule — §5.1's tables are keyed on the message — so it ends with
-` (see rigc guide §5.1)`, the section its row is in.
+on stderr, exit 1 (§5.5). A compile error carries a stable `CE_` code and points
+at that code's one row in §5.1. Only a legacy uncoded library error ends with
+` (see rigc guide §5.1)`. `--all` takes a section address; with a rule name it is
+a usage refusal, exit 2 — omit it to read the row.
 
 📥 **A third surface is `ingest`'s, and it is not a failure at all.** What a skeleton
 holds and the spec format cannot say is **recorded** rather than refused — one coded
@@ -6830,7 +6835,9 @@ Library callers may still construct an uncoded `CompileError`; only that legacy
 case points at `§5.1`. `NotImplementedError` keeps its class and the same pointer.
 
 Use `rigc guide §5.1.<k>` for a whole numbered `####` group; every group is at most
-30,000 UTF-8 bytes including the command's heading. The guide remains one ledger:
+30,000 UTF-8 bytes including the command's heading. `rigc guide §5.1` prints this
+introduction and the group index, also at most 30,000 printed UTF-8 bytes;
+`rigc guide §5.1 --all` explicitly asks for every group's body. The guide remains one ledger:
 the command reads these rows at call time, without a generated copy. Unknown
 codes are refused with the three nearest real names and exit 1. `<value>` and
 other angle-bracket placeholders below stand for values supplied by the input;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spine-rigc",
-  "version": "2.58.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,11 +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 its stable `CE_` code row. `rigc guide §5.1.<k>`
-prints a numbered compile-error group of at most 30,000 UTF-8 bytes; only legacy
-uncoded library errors point 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,11 +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 its stable `CE_` code row. `rigc guide §5.1.<k>`
-prints a numbered compile-error group of at most 30,000 UTF-8 bytes; only legacy
-uncoded library errors point 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,11 +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 its stable `CE_` code row. `rigc guide §5.1.<k>`
-prints a numbered compile-error group of at most 30,000 UTF-8 bytes; only legacy
-uncoded library errors point 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,11 +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 its stable `CE_` code row. `rigc guide §5.1.<k>`
-prints a numbered compile-error group of at most 30,000 UTF-8 bytes; only legacy
-uncoded library errors point 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,11 +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 its stable `CE_` code row. `rigc guide §5.1.<k>`
-prints a numbered compile-error group of at most 30,000 UTF-8 bytes; only legacy
-uncoded library errors point 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/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.',
     ],

package/src/guide.ts

@@ -380,10 +380,12 @@ function childrenOf(sections: readonly GuideSection[], address: string | null):
  *
  * - a rule: per row, `docs/AUTHORING.md §<addr>, line <N> — under "<heading>"`, then the row verbatim;
  * - a section: `docs/AUTHORING.md §<addr> "<title>", lines <a>–<b>, <X.X> KB`, then — when it has children — one
- *   `§<addr>  <X.X KB>  <title>` line per child, then the section verbatim;
+ *   `§<addr>  <X.X KB>  <title>` line per child, then its heading and own prose;
+ *   `all` includes its children's bodies too. A leaf is always printed verbatim.
+ *   The header and index sizes describe the full ledger spans, not the shortened answer;
  * - an unknown rule or section: a refusal by `GUIDE_RULE_KNOWN` / `GUIDE_SECTION_KNOWN`.
  */
-export function guideAnswer(asked: string, texts: GuideTexts): GuideAnswer {
+export function guideAnswer(asked: string, texts: GuideTexts, options: { all?: boolean } = {}): GuideAnswer {
   const sections = guideSections(texts.guide);
   if (asked.startsWith('§')) {
     const address = asked.slice(1);
@@ -401,10 +403,11 @@ export function guideAnswer(asked: string, texts: GuideTexts): GuideAnswer {
         detail: `"${asked}" — no such section; the deepest that exists is ${where}, whose sections are: ${kids.length === 0 ? 'none' : kids.join(', ')}`,
       };
     }
-    const body = texts.guide.split('\n').slice(section.firstLine - 1, section.lastLine).join('\n').replace(/\n+$/, '');
     const lines = [`${GUIDE_FILE} §${section.address} "${section.heading.title}", lines ${section.firstLine}–${section.lastLine}, ${kb(section.end - section.start)}`];
     // A chapter lists its ###, a ### its #### — each with the address that prints it, its size and its title.
     const subs = childrenOf(sections, section.address);
+    const lastLine = !options.all && subs.length > 0 ? subs[0].firstLine - 1 : section.lastLine;
+    const body = texts.guide.split('\n').slice(section.firstLine - 1, lastLine).join('\n').replace(/\n+$/, '');
     const wide = Math.max(0, ...subs.map((sub) => sub.address.length + 1));
     const wideKb = Math.max(0, ...subs.map((sub) => kb(sub.end - sub.start).length));
     for (const sub of subs) lines.push(`${`§${sub.address}`.padEnd(wide)}  ${kb(sub.end - sub.start).padStart(wideKb)}  ${sub.heading.title}`);