Need-segmented skill docs (rigging / motion / face / ingest) built from one source

[firejune]

Why

Zero-install skill-doc distribution demonstrably works: the closest comparable project ships one self-contained SKILL.md (scripts embedded by CI) that users paste into an AI assistant, and that friction-free onboarding plausibly explains much of its adoption. rigc can ship the same channel without giving up the CLI: build skill docs from the AUTHORING.md / PROMPTING.md sources.

Decided design (2026-08-25)

• Segment by need, not one monolithic doc. Narrow trigger descriptions match better and the set reads as a capability catalog:
  • rigging/joints — parts → bone hierarchy, pivots
  • motion authoring — animations onto an existing rig
  • face/expression — blink/mouth overlay attachments
  • ingest & repair — normalize/re-pivot an external skeleton.json (external-rig intake; pairs with A/B voting loop: compile first, humans break instrument ties in a shareable preview, votes land in an AI-first ledger #151)
• Single source, thin built fronts. Shared core (Spine JSON knowledge, the CLI loop, the verification protocol) lives once; a build step embeds it into each segment doc. (Embed-build pattern observed in the comparable project — idea only; that repo is PolyForm NC, any code clean-room.)
• Which segment ships first is decided by intake signals (community thread, issues), not by prediction.

Status

Design settled; awaiting a demand signal before building any segment.

[firejune]

Second segment landed, and the deferred question is settled

INGEST — docs/INGEST.md, PR #268. The ingest & repair segment: what the CLI
will and will not do with a foreign skeleton.json, transcribing one into rig+motion
specs, the realistic refusals a user meets, and the re-pivot / rename / extend
recipes. Ships in files like AUTHORING.md and MOTION.md. Two segments of four
now exist (motion, ingest); rigging and face stay open and follow demand.

Decision on "single source, thin built fronts" — keep hand-written fronts. No shared core, no build step.

PR #245 deferred this until a second segment existed. It now does, and the prediction
in #245 — that the pivot and coordinate material would be the overlap zone — turned
out to be wrong, which is what decides it.

Measured overlap across the three fronts (shared word-runs, fenced code blocks
stripped):

Pair	shared 10-word runs	shared 15-word runs
INGEST ∩ MOTION	36 / 7844 (0.46 %)	19 / 7848 (0.24 %)
INGEST ∩ AUTHORING	2 / 7844 (0.03 %)	0 / 7848 (0.00 %)
MOTION ∩ AUTHORING	74 / 8412 (0.88 %)	35 / 8437 (0.41 %)

And the 19 shared runs between the two new segments collapse to two sentences of
header boilerplate — the "AUTHORING.md is the file formats, the failure map and the
CLI" preamble, and the "if you are the person operating an agent" pointer. That is
the entire duplication a build step would have been extracting.

Reasons

1. The material that looks shared is already single-sourced — in AUTHORING.md and
   in the code. The coordinate contract lives once (AUTHORING §11.2 +
   src/transform.ts, under a standing "do not open-code this" rule) and both fronts
   cite it. The pivot material split along a real seam instead of duplicating:
   MOTION §3.9 decides which pivot when two poses under-determine it; INGEST §4.1
   states what fields change to move one that exists, and measures the consequence.
   They cross-reference each other, which a generator could not have produced and
   which is better than two copies of a paragraph.
2. The same fact reads differently per segment, and that is content, not
   formatting. "A pivot is invisible in either end pose" is a warning about
   under-determination to MOTION's reader and an acceptance criterion (with arithmetic
   and a --viewport caveat) to INGEST's. An embed ships one register to both readers.
3. The docs are the published interface and there is no build step for them. They
   ship in files; npm pack --dry-run is the check. A generator adds a way for the
   shipped copy to disagree with its source, a CI gate to keep them equal, and a second
   thing to learn before editing a doc — complexity that has to be paid for by
   duplication that does not exist.
4. The drift that actually happens is citation drift, not prose drift. PR docs(skill): the ingest recipe — reading, transcribing and re-pivoting a foreign skeleton #268 is
   the demonstration: the base moved under it mid-flight (feat(emitter): atlas packer and importer — parts onto shared pages, and a pack as an input #263 landed the atlas packer
   and importer, closing B3 (emitter half): no atlas packer and no importer for a pre-packed atlas #4) and what went stale was a claim about the tool in one
   section, not a shared passage. Fixing it meant re-running the commands and rewriting
   two sections — a build step would have made that neither easier nor safer.

The overlap-watch rule, so this is reversible on evidence

Extract a shared core when a segment has to restate a passage another front already
carries — the test being a reader of either front needs the same paragraph, not
merely the same fact. Until then: a fact two fronts need lives in AUTHORING.md (or
in the code) and both cite it; a fact that reads differently per reader is written
twice on purpose.

Concrete trigger for the next segment: RIGGING.md is the likely one and
parts → hierarchy → pivots is where it would bite. If that document cannot state its
pivot material without copying either MOTION §3.9 or INGEST §4.1, that is the signal —
and the extraction target is those two sections, not the whole header.

Explicitly not built: no docs/_shared/ fragments, no embed script, no CI equality
gate. Tooling for two boilerplate sentences would have to earn its complexity first.

Bookkeeping

The design bullet above ("Single source, thin built fronts") is now superseded by
this comment. Two findings surfaced while verifying the segment and are filed
separately: #262 and #267.