@rig-c/create 0.0.0-stage → 1.0.1

package/docs/COLLECTIONS.md

@@ -0,0 +1,337 @@
+# Collections
+
+Several rigs that belong together — characters cut from one group painting,
+wearing one outfit set, sharing a pose, composed into one lineup — are a
+**collection**. Shared direction is given once and inherited; a member answers
+only what differs; one reference member goes first and sets the direction for
+the rest; composition belongs to the collection; and a collection version pins
+the exact member builds it was made from. The empty skeleton is
+[../templates/collection.json](../templates/collection.json) with
+[../templates/shared/conventions.json](../templates/shared/conventions.json);
+the schema is `rig-create/collection@0`, v0 like a project's
+([PROJECT.md](PROJECT.md)).
+
+## Layout
+
+```
+<collection>/
+  collection.json      shared interview, member order, cross bars, composition, pins
+  AGENTS.md            the collection's agent guide; CLAUDE.md imports it
+  package.json         the rig-c packages, pinned once for every member
+  shared/
+    conventions.json   conventions every member follows
+  members/<name>/      an ordinary project (the layout in PROJECT.md), without package.json or .git
+  inputs/              the group painting, shared references
+    references/
+  evidence/v<N>/       what a collection verdict rested on
+  derived/             regenerable (ignored by git)
+  outputs/v<N>/        lineup, outfit-switch takes (ignored by git)
+  scratch/             (ignored by git)
+```
+
+### Making one
+
+```
+rig-create init --collection <dir> [--no-install]
+rig-create init --member <collection dir> <name>
+```
+
+`init --collection` writes the layout above: `collection.json` and
+`shared/conventions.json` from the templates, both named after the folder, a
+`.gitignore` for the untracked folders, the `package.json` pins, the install
+(unless skipped), the agent guide, and a first commit of exactly those files.
+**The collection is one git repository.** A collection version pins member
+builds, so the collection's history has to hold the member records it pins; a
+member with a repository of its own would be an opaque gitlink to it.
+
+`init --member` takes the collection folder and a **name**, not a path: it
+derives `members/<name>/`, so a member cannot be made outside `members/`, and a
+folder that is not a collection is refused (`INIT_NOT_A_COLLECTION`) before
+anything is written. It writes an ordinary project there (`project.json`,
+`.gitignore`, `inputs/references/`, `evidence/`, the ignored folders, the
+agent guide, its doc links pointing at the collection's install), registers it
+in `collection.json` `members[]` (`{ name, project, input: null, note: null }`),
+and commits exactly those files and `collection.json` in the collection's
+repository. It has **no `package.json` and no repository of its own**: the
+collection pins the packages once, so every member is built with the same
+versions and a cross bar measures one toolchain; `interview --check` in a
+member reads the collection's install.
+
+Every framing answer, waypoint guide and post item guide the collection gave
+starts in the member as an `inherited` reference (below), written with
+`"by": "rig-create"`. Where the collection's answer is `null` or `"per-member"`,
+the member's starts `null`: the member's own question, asked in its interview.
+Refused by name: a duplicate (`INIT_MEMBER_EXISTS`, in `members[]` or as a
+folder), a name that is not one folder name (`INIT_MEMBER_NAME_INVALID`), a
+collection with no `name` (`INIT_COLLECTION_UNNAMED`), and a `collection.json`
+with uncommitted changes (`INIT_COLLECTION_DIRTY`), so the member's commit never
+carries someone else's edit. Outside a git work tree the files are written and
+nothing is committed.
+
+### Members live inside the collection
+
+`members/<name>/project.json`, not top-level projects referenced by name. A
+member's input is cut from the collection's painting and its interview inherits
+the collection's answers, so it has exactly one parent; a top-level project that
+two collections referenced would inherit two answers to the same question. A
+character wanted somewhere else is a new project, which may point at this one.
+The folder path is the membership record, so `project.json` needs no
+back-pointer and keeps its shape.
+
+## What the collection owns
+
+| Field | Holds |
+| --- | --- |
+| `interview.questions[]` | Questions with `scope: "collection"`, answered here only (`id`, `scope`, `text`, `source`, `answer`, `history[]`): `members`, `reference_member`, `style`, `outfits`, `composition`. Same answer shape as [INTERVIEW.md](INTERVIEW.md#answer-shape). |
+| `interview.framing[]`, `interview.waypoints[]`, `interview.post` | The INTERVIEW.md guides, given **once** for every member. An answer whose `value` is `"per-member"` leaves that guide to each member. |
+| `plan.order[]` | One entry per phase (`phase`, `members[]`, `runs`: `alone` or `parallel`, `rests_on[]`, `ends_with`). Phase 1: the **reference member** goes alone through its own `interview` → `rig-review`. Phase 2: the rest, in parallel once their interviews are signed — a member's own interview still runs one at a time, because an interview needs the user's full attention and parallel interviews produce contradicting answers. |
+| `plan.cross_bars[]` | Bars measured across members, e.g. *the shared pose plays exactly on every member in every outfit*. Each names the answers it rests on (`rests_on`), which members and variants it covers, and the `receipt` that measured it. |
+| `plan.steps[]` | Composition steps — post-production at collection level — same shape as a project's post steps ([PROJECT.md § The plan](PROJECT.md#the-plan)). |
+| `members[]` | `name`, `project` (path to its `project.json`), `input` (where its painting comes from: its own file, or a crop of the shared one), `note`. |
+| `shared` | Path to `shared/conventions.json`: the variant (outfit) set, shared motion, shared pose, bone naming — what every member follows. It points at files by path rather than copying them. |
+| `composition` | `lineup`, `layers[]` (who overlaps whom), `outputs_wanted[]`. **Composition belongs to the collection, never to a member**: a member's project does not hold a lineup or a group take, so a lineup cannot drift between two members' records. |
+| `inputs[]`, `derived[]`, `archive`, `notes[]` | As in a project. |
+| `versions[]` | Collection versions, each with `pins` (below), `composition_inputs`, `outputs`, `evidence`, `verdicts`, `changed`, `answers_feedback`. |
+| `signoffs[]`, `stage`, `stage_values` | As in a project, with the collection's stages (below). |
+
+### Deferring a collection question
+
+Only `interview.questions[]` entries with `scope: "collection"` may be
+explicitly deferred. Record the person's or delegate's decision with
+`rig-create collection answer composition <dir> --by <who> --defer-until post-interview --reason-file <file>`.
+File paths are relative to the collection folder, or absolute. The reason
+file supplies nonblank text unchanged. The writer records
+`{ "deferred": { "by": "…", "at": "…", "reason": "…", "until_stage": "post-interview" } }`
+as the question's `answer`, with `at` set from the clock. `until_stage` must
+be an ordered collection lifecycle stage strictly later than the effective
+current stage. `paused` is excluded as a deadline. A paused collection uses
+its effective stage, as the collection check already does.
+
+Before the deadline the check emits `COLLECTION_ANSWER_DEFERRED`, preserving
+its exit status. At the deadline it refuses `INTERVIEW_INCOMPLETE`, and past
+it `COLLECTION_ITEM_SILENT`. Resolve the deferral with
+`rig-create collection answer composition <dir> --by <who> --value-file <file>`.
+That file contains an ordinary answer object in the
+[interview answer shape](INTERVIEW.md#answer-shape), including `verbatim`
+and `value` for a user answer. The writer sets its `by` and `at`. Both forms
+validate the candidate with the collection record check before writing;
+unrelated pre-existing refusals may remain. Refused writes leave the bytes
+unchanged. The previous non-null answer moves into the question's `history[]`
+when that array exists, including when an ordinary answer replaces a
+deferral. Without a history array it is simply replaced. All bytes outside
+the answer and history values remain unchanged.
+
+A deferral supplies no inherited value. New members start with a null answer
+where a shared answer is deferred, and an existing inherited reference to a
+deferred answer resolves as silence. Member-local deferrals and deferrals on
+framing, waypoint or post guides refuse `ANSWER_MALFORMED`. Their existing
+stage gates remain the way post items wait for their interview.
+
+### `shared/conventions.json`
+
+| Field | Holds |
+| --- | --- |
+| `schema` | `rig-create/conventions@0` |
+| `collection` | the collection's `name` |
+| `variants` | `values[]` (outfit or other variant names), `source` (the answer they come from), `what_changes`, `what_stays` |
+| `shared_motion` | `source` (which member's or file's motion every member plays), `note` |
+| `shared_pose` | `what` (the pose every member shares), `receipts[]` (the measurements that showed it plays on each) |
+| `bone_naming` | `declared` (the naming rule), `observed` (what the builds actually use, if it differs) |
+| `notes[]` | free text |
+
+## Inherited, overridden, own
+
+A member answers the same questions as any project, and every one of its
+answers carries a `basis`:
+
+| `basis` | Meaning | Shape |
+| --- | --- | --- |
+| `inherited` | The collection's answer applies unchanged. The value is **not copied**: it is read from the collection, so a later change to the collection answer reaches the member. | `{ "basis": "inherited", "from": { "collection": "<name>", "question": "<id>" }, "by": "interviewer", "at": "…" }` |
+| `overridden` | The collection answered, and this member differs. A user answer (or a delegation) plus what it overrides and the user's reason. | the user-answer or delegated shape, plus `"basis": "overridden"`, `"overrides": { "collection", "question", "collection_answer_at" }`, `"why_verbatim"` |
+| `own` | The collection did not answer it, or answered `"per-member"`. An ordinary answer. | the user-answer, delegated or not-applicable shape, plus `"basis": "own"` |
+
+An inherited answer is a reference, not a copy:
+
+```json
+{ "basis": "inherited", "from": { "collection": "harbour", "question": "motion" },
+  "by": "interviewer", "at": "2026-11-12T10:00:00Z" }
+```
+
+An override keeps what it overrides and why, so a later reader sees why one
+member differs:
+
+```json
+{ "basis": "overridden",
+  "overrides": { "collection": "harbour", "question": "constraints", "collection_answer_at": "2026-11-11T15:00:00Z" },
+  "delegated": false, "by": "user", "at": "2026-11-12T10:04:00Z",
+  "verbatim": "Put physics on her skirt.",
+  "why_verbatim": "Hers is long; the others are short.",
+  "value": [{ "part": "bottomwear", "effect": "physics" }] }
+```
+
+An inherited answer is resolved before use: if the collection's answer is
+delegated, the member inherits the delegation and the agent's decision with it,
+and a bounce on it is attributed to the collection's answer as delegated. An
+override is the record of why one member differs; it is never written to make a
+member match what the agent already built.
+
+### Recording a member override
+
+`interview-answer` replaces an inherited answer locally. If `classify()`
+resolves the shared answer as silent (withdrawn to `null`, or a user answer
+of `"per-member"`), it records `basis: "own"` with no `overrides` and no
+required `--why-file`. A shared delegation remains shared, as classified,
+even when its agent decision says `"per-member"`. These cases are exercised
+through the writer and member check in `tests/choices.test.ts`.
+
+When a shared answer still applies, the writer records `basis: "overridden"`.
+Supply `--why-file <file>` with either the ordinary
+pick flags or `--from-review <actId>` to ingest the finalized job act. The
+file must contain nonblank UTF-8. Its exact text, including spaces and
+newlines, becomes `why_verbatim`; a note, an option label or agent reasoning
+is not a substitute. A fresh replacement of an overridden answer requires a
+fresh reason file too. Missing, blank or unreadable reasons refuse before
+writing, leaving `project.json` byte-identical.
+
+The writer fills `overrides` from the inherited collection reference and the
+resolved answer's `at`. When replacing an override it preserves that original
+reference. A legacy overridden answer without `overrides` recovers its
+reference from the most recent inherited record in the item's `history[]`,
+using the same collection-answer lookup as a fresh override. It retains
+earlier local answers in history and never changes the parent collection.
+These writer paths are covered by `tests/choices.test.ts`.
+
+The member check validates overrides in current answers and `history[]`:
+`overrides.collection` names the parent collection, `overrides.question`
+names a question it answered, and `collection_answer_at` exactly matches a
+current or historical answer's `at`. A later collection answer does not
+invalidate a reference whose source remains in history. Every override needs
+nonblank `why_verbatim`. These checks also run before an override write.
+`OVERRIDDEN_ANSWERS_SINCE = 2026-11-06T00:00:00Z` dates the contract by the
+member answer's own `at`: earlier invalid records WARN; records on or after
+that date, or without a readable date, refuse. The checks and date boundary
+are covered by `tests/overrides.test.ts`; codes are in [CHECKS.md](CHECKS.md#refusals).
+
+## Collection stages
+
+`interview` → `plan-approved` → `reference` → `members` → `post-interview` →
+`post` → `direction-review` → `accepted`, plus `paused`. Same rule as a
+project: a stage moves only on a human `signoffs[]` entry. User step 1 (base
+motion) runs in each member; the collection's own steps 2 and 3 are its
+composition.
+
+| Stage | User step | What happens | Ends with |
+| --- | --- | --- | --- |
+| `interview` | 1 | The collection questions and the shared guides are answered. | The user signs `{ "stage": "interview" }`. |
+| `plan-approved` | 1 | Order and cross bars are drafted and signed. | `{ "stage": "plan-approved" }`. |
+| `reference` | 1 | The reference member runs its own stages through `rig-review`. | The user signs `{ "stage": "reference" }`: *this is the direction for the rest*. Separate from the member's own acceptance, because accepting one rig is not agreeing it sets everyone's direction. |
+| `members` | 1 | The other members run through `rig-review`, in parallel once their interviews are signed. | Every member's rig accepted; every cross bar met. |
+| `post-interview` | 2 | Composition guides — lineup, overlaps, camera, timing — and the composition steps. | `{ "stage": "post-interview" }`. |
+| `post` | 2 | Lineup, layers, collection outputs, each frozen as a collection version with its pins. | The composition steps' bars are met. |
+| `direction-review` | 2 → 3 | The user reviews one collection version. Feedback on one member's rig goes back to that member's waypoints (`on_items[].member` names it). | The user accepts it. |
+| `accepted` | — | Done. | — |
+| `paused` | — | Stopped by a human sign-off. | — |
+
+## Pins: a member change never silently changes a collection output
+
+A collection version pins its members like a lockfile. Each pin names the
+member's version **and** the content hashes of every rig it used (model, atlas,
+config, per variant):
+
+```json
+"pins": [
+  { "member": "keeper", "version": 2, "rigs": [
+      { "variant": "default", "files": [
+          { "role": "model", "path": "outputs/v2/skeleton.json", "sha256": "…" },
+          { "role": "atlas", "path": "outputs/v2/atlas.atlas", "sha256": "…" },
+          { "role": "atlas", "path": "outputs/v2/atlas.png", "sha256": "…" },
+          { "role": "config", "path": "derived/v2/config.json", "sha256": "…" } ] },
+      { "variant": "winter", "files": [ … ] } ] }
+]
+```
+
+A rig is a list of files, not one hash per role: an atlas is its `.atlas` text
+and one or more page images, and one `atlas_sha256` cannot pin them. Paths are
+relative to the member's folder.
+
+The hashes bind the build named by a pin. An explicitly selected member
+version remains locked when newer member builds are recorded. A default pin
+keeps the latest-build check described below. A collection output whose
+recorded sources do not hash to its pins is stale and is not shown.
+
+Where a member has no `versions[]` yet (work that predates this structure), the
+pin carries `"version": null` and the hashes alone, and says so in `note`.
+
+### Recording a collection version
+
+```
+rig-create collection pin [<dir>] [--changed <sentence>] [--member <name>=<version>]...
+```
+
+Run when a collection output is made: put it in `outputs/v<N>/` (`N` the next
+collection version), then pin. It appends `versions[]` entry `N` to
+`collection.json` with `pins`, the sha256 and size of every file under
+`outputs/v<N>/`, `changed`, and empty `composition_inputs`, `evidence`,
+`verdicts` and `answers_feedback` to fill. It writes, it does not commit.
+
+Repeat `--member <name>=<version>` to select an existing rig version by its
+positive integer `n`, for example `--member first=1 --member second=2`.
+A name may appear only once and must be in `members[]`; malformed selectors,
+unknown members and absent or non-rig versions refuse with
+`PIN_SELECTION_INVALID`, before any write. Unspecified members use their
+**latest rig version** (`kind: "rig"` or no kind, highest `n`). Only explicitly
+selected pins carry `"selection": "explicit"`. The writer-generated
+`tests/fixtures/collection-pin.json` locks one earlier build and leaves one
+member at latest; `bun scripts/generate-collection-pin-fixture.ts <fresh dir> --check` reproduces it. `tests/collection-pin-select.test.ts` covers selection,
+byte-identical refusals and every pinned hash across variants.
+
+The rig files are read from the selected/default version: each `outputs[]` entry that is
+a model (`.json`, `.skel`) or an atlas (`.atlas`, page images), or that names
+its own `role`; and `provenance.config`, for every variant. An output names its
+variant with `variant` (default `default`); a take or a contact sheet is not a
+rig file and is not pinned. Every file present on disk is hashed there.
+Refused by member name, all at once and nothing written: a member with no
+project record (`MEMBER_PROJECT_MISSING`), no rig version or no rig file
+(`PIN_NO_BUILD`), and a file on disk that no longer hashes to the version that
+lists it (`PIN_SOURCE_DRIFT`) — it was rebuilt in place; record a new member
+version first, so the pin names a build that exists.
+
+### The pin check
+
+```
+rig-create collection --check [<dir>] [--json]
+rig-create interview --check <collection dir | collection.json>
+```
+
+Both run the same check. The pins checked are those of the **latest collection
+version that has outputs** — the one a person would be shown; a version pinned
+before its output exists is not checked yet. Every member in `members[]` is
+compared with its pin according to its selection mode:
+
+| Pin mode | Version compared | A newer member version alone |
+| --- | --- | --- |
+| Default, no `selection` | Latest rig version, which must match the recorded pin version | `PIN_STALE`; make and pin a new collection output |
+| Explicit lockfile, `"selection": "explicit"` | The recorded rig version `n` | No change; the lock remains valid |
+| Legacy, `"version": null`, no `selection` | Hashes alone while the member has no rig versions | `PIN_STALE` when a rig version appears |
+
+Existing default and legacy behavior is retained (`tests/collections.test.ts`).
+Explicit locks refuse when the recorded version disappears, its file list or
+variant changes, or its recorded/present-on-disk hashes differ from the pin
+(`tests/collection-pin-select.test.ts`). Each difference names the member:
+
+- `PIN_STALE members[<name>]`: a default pin's latest rig version is not the
+  pinned one, or an explicit pin's recorded rig version is absent; a pinned file's sha256 (on disk where present, else as recorded)
+  differs from the pin; a pinned file is no longer listed; a rig file of the
+  version is not pinned. For a `"version": null` pin, a member that now has
+  versions, or a pinned file on disk that no longer hashes to it.
+- `PIN_MISSING members[<name>]`: a member the pinned version does not pin.
+- `PIN_UNKNOWN_MEMBER members[<name>]`: a pin for a name not in `members[]`.
+
+The check also reads the collection record: schema, stage (from the collection
+stages above), sign-offs (human, known stage, every `signoff` stage passed is
+signed, `paused` signed), the collection's own questions, framing answers and
+waypoint guides (`INTERVIEW_INCOMPLETE` at `interview`, `COLLECTION_ITEM_SILENT`
+after it; post item guides the same from `post-interview`), and that every
+`members[]` entry has its `project.json`. It does not check `plan.order`, the
+cross bars or composition, and it does not run each member's interview check:
+run `interview --check` in the member. Codes: [CHECKS.md § Collections](CHECKS.md#collections).

package/docs/CRAFT.md

@@ -0,0 +1,277 @@
+# Craft notes
+
+Lessons learned from rigs that were sent back in review, written down so the next
+interview starts from them instead of repeating them. Each note is filed under the
+waypoint where it is asked (see [INTERVIEW.md](INTERVIEW.md) for the waypoints and
+the answer shape) and carries the default the interviewer proposes there.
+
+**A note is a proposal, never a decision.** The interviewer reads the default out
+("Usually … — shall we?") and records the user's answer verbatim as the guide for
+that waypoint. A "yes" is what makes the default the user's; a different answer
+replaces it. A note is never ground for the agent to decide alone, and a default
+nobody was asked about decides nothing.
+
+**Direction and execution are kept apart.** A note here is a design call: a
+reasonable user could answer it either way. A seam, a hole or a smeared plate is
+not a design call — nobody would answer "yes" to it — so it is never asked at the
+interview. Those defects are listed at the end, [for the gates](#for-the-gates-not-the-interview),
+with the bar that would catch each. The checks an agent runs on every version
+before anyone looks, and the review lessons behind them, are in
+[LESSONS.md](LESSONS.md).
+
+Each note has the same shape: the lesson, why it matters, the waypoint, and the
+proposed default.
+
+## Framing
+
+### F1. Two kinds of rig
+
+- **Lesson**: an illustration brought to life and a character made to perform are
+  different rigs. Walking, running and other travelling motion belong only to the
+  second.
+- **Why**: treating a still illustration as a performer invites motion the
+  painting cannot carry — feet, a ground line and a back it never drew — and the
+  result reads as a puppet instead of a living picture.
+- **Waypoint**: `rig_type`
+- **Proposed default**: "This reads as an illustration to bring to life — usually
+  idle breath, expression, and hair and cloth on physics, with no walking or
+  running. Shall we?"
+
+### F2. What the painting leaves out stays out
+
+- **Lesson**: what the painting does not show is not a defect to repair, and no
+  part is invented to fill it.
+- **Why**: a part invented outside the frame — legs below the crop, a hidden
+  back — has no painted source, so it never matches the style and draws the eye
+  to exactly what the composition chose to hide.
+- **Waypoint**: `rig_type`
+- **Proposed default**: "Usually what lies outside the painting — legs below the
+  frame, a hidden back — stays out, and the rig works with what is drawn. Shall
+  we?"
+
+## `seethrough`
+
+No interview note yet. How to run the split, check it and re-run it is
+execution, not a design call, so it is not asked: it is in [SOURCE.md](SOURCE.md),
+read before `seethrough` and `assemble`, with the cutting rules for `assemble`.
+
+## `assemble`
+
+### A1. Cut the bust, not the waist
+
+- **Lesson**: give the chest its own part, so it can carry volume and motion,
+  rather than cutting the torso across the waist.
+- **Why**: a waist cut is the seam the eye watches most during a breath, and it
+  opens; a separate bust part moves on its own without any seam across the body.
+- **Waypoint**: `assemble`
+- **Proposed default**: "Usually the bust is its own part and the torso is not
+  cut at the waist. Shall we?"
+
+### A2. Limbs that bend are cut at the joint and rounded
+
+- **Lesson**: an arm or leg that has to bend is cut at the elbow or knee, with the
+  seam rounded in an image editor, and bends only within a small range; a larger
+  bend is a replacement drawing.
+- **Why**: a limb cut anywhere else, or bent further than its overlap covers,
+  shows a straight cut edge or a gap at the joint.
+- **Waypoint**: `assemble`
+- **Proposed default**: "Usually an arm or leg that bends is cut at the elbow or
+  knee with a rounded seam and bends only a little; anything bigger gets its own
+  drawing. Shall we?"
+
+### A3. Soften a cut through skin, not a designed edge
+
+- **Lesson**: a cut through continuous skin gets a soft alpha edge; a cut along
+  an edge the design already draws stays hard.
+- **Why**: a hard edge across bare skin shows as a line when the parts move apart
+  by a pixel, while softening an edge the artist drew on purpose — a cuff, an
+  armour plate — blurs the design.
+- **Waypoint**: `assemble`
+- **Proposed default**: "Usually a cut across bare skin gets a soft edge, and a
+  cut on a drawn edge such as a cuff or an armour plate stays sharp. Shall we?"
+
+### A4. The user marks where the arm ends and the sleeve begins
+
+- **Lesson**: where an arm and its sleeve share one layer, the boundary between
+  them is a design call shown to the user before rigging, and only the sleeve side
+  moves on physics.
+- **Why**: a boundary guessed by the agent puts skin on the cloth chain or cloth
+  on the rigid arm, and either one is only noticed in motion.
+- **Waypoint**: `assemble`
+- **Proposed default**: "Usually we show you where the arm ends and the sleeve
+  begins before rigging, and only the sleeve sways. Shall we?"
+
+### A5. Variants of one character live in one rig
+
+- **Lesson**: outfits or other variants of one character are swappable sets in one
+  rig, not one rig per variant.
+- **Why**: one rig per variant multiplies every later fix and lets the variants
+  drift apart in bones and motion. In a collection this is answered once, at the
+  collection level, and inherited by its members.
+- **Waypoint**: `assemble`
+- **Proposed default**: "Usually each character is one rig with its outfits as
+  swappable sets. Shall we?"
+
+## `bones`
+
+### B1. Hands are not cloth
+
+- **Lesson**: hands and arms ride their own bones, driven by keys, never the tip
+  of a cloth chain.
+- **Why**: a hand weighted to the soft end of a sleeve's physics chain flaps like
+  a paper doll whenever the sleeve moves.
+- **Waypoint**: `bones`
+- **Proposed default**: "Usually arms and hands get their own bones and stay
+  rigid, with the sleeve swaying around them. Shall we?"
+
+## `meshes`
+
+### M1. The torso bends as one piece
+
+- **Lesson**: the torso bends as one weighted mesh, not as cut pieces moved
+  rigidly.
+- **Why**: rigid pieces moved against each other open at the seam, and the
+  background shows through the body in motion even when every still frame looks
+  closed.
+- **Waypoint**: `meshes`
+- **Proposed default**: "Usually the torso is one piece that bends with the
+  breath. Shall we?"
+
+### M2. The bust is meshed unless there is a reason
+
+- **Lesson**: the bust is meshed with its own regions by default, so the chest
+  can carry volume and motion. It is left out only for a stated reason.
+- **Why**: a chest bent as part of a plain torso mesh moves like the waist, flat;
+  and an exclusion nobody gave a reason for cannot be reviewed later.
+- **Waypoint**: `meshes`
+- **Asked instead of a default**: the default is not proposed; the exclusion is
+  asked: "Is there a reason to leave the bust out, such as a rigid breastplate?"
+  No reason keeps the default. A reason is recorded with the exclusion in the
+  `x_deform` value ([INTERVIEW.md](INTERVIEW.md)), and the agent passes it to
+  parts as the opt-out (rig-c/parts#986).
+- **Body, not cloth**: bust motion is body motion. The rule that fitted cloth
+  gets no physics is about cloth: a fitted top is not a reason to leave the bust
+  out, nor to drop its jiggle (C2).
+
+## `constraints`
+
+### C1. Hair and loose cloth on physics, soft enough to trail
+
+- **Lesson**: hair and loose cloth move on physics, soft enough to trail the body.
+  The rig supplies the response; the consumer supplies the wind.
+- **Why**: hair keyed by hand repeats visibly, and a chain stiff enough to hold
+  its pose reads as one solid piece — the rig looks stiff even though physics is
+  on.
+- **Waypoint**: `constraints`
+- **Proposed default**: "Usually hair and loose cloth are on physics, soft enough
+  to trail the body, and the rig does not bake in a wind of its own. Shall we?"
+
+### C2. Chest volume comes from jiggle
+
+- **Lesson**: a chest reads as having volume when its own part jiggles a beat
+  behind the breath.
+- **Why**: a chest that moves exactly with the torso reads as painted on, flat.
+- **Waypoint**: `constraints`
+- **Proposed default**: "Usually the bust jiggles a little, a beat behind the
+  breath. Shall we?"
+
+### C3. A hem over nothing stays down
+
+- **Lesson**: a long hem with nothing painted under it moves only so far that the
+  empty space beneath never shows.
+- **Why**: a hem that swings freely lifts off empty canvas where feet or ground
+  should be, and the figure looks like it floats.
+- **Waypoint**: `constraints`
+- **Proposed default**: "Usually a long hem with no feet painted under it moves
+  only slightly. Shall we?"
+
+## `motion`
+
+### Mo1. A small breath; the body must not squash
+
+- **Lesson**: breath is a small rise of the chest with the hips held where they
+  are.
+- **Why**: a breath large enough to stretch the torso, or one that moves the hips
+  with it, reads as the body squashing rather than breathing.
+- **Waypoint**: `motion`
+- **Proposed default**: "Usually breath is a small chest rise, once per loop, with
+  the hips held still. Shall we?"
+
+## Post-production
+
+These are asked after the rig is accepted, never at a rig waypoint: depth and
+camera work are direction applied to a finished rig, not part of rigging.
+
+### P1. Depth is judged by eye
+
+- **Lesson**: depth is judged by whether a turn reads as solid beside the
+  reference, not by how closely a depth map matches.
+- **Why**: a depth map can match well and still turn badly, and a rougher one can
+  turn convincingly; only the turn on screen is what the viewer sees.
+- **Waypoint**: `camera_depth`
+- **Proposed default**: "Usually we judge the 2.5D turn by eye, side by side with
+  the reference. Shall we?"
+
+### P2. Show depth on a gaze path, not a sweep
+
+- **Lesson**: depth is shown on an irregular gaze path with pauses, or together
+  with a motion such as an arm turn; a steady back-and-forth sweep is for finding
+  defects, not for showing depth.
+- **Why**: the eye does not read a mechanical sweep as a solid head turning; it
+  reads a look that wanders and settles.
+- **Waypoint**: `camera_depth`
+- **Proposed default**: "Usually the turn is shown as a gaze wandering with
+  pauses. Shall we?"
+
+### P3. A head-turn needs an upright head
+
+- **Lesson**: a head already tilted in the painting breaks under a turn; that is a
+  limit of the input, not of the tool.
+- **Why**: turning a tilted head moves its features along the wrong axis, and the
+  skull reads as broken.
+- **Waypoint**: `camera_depth`
+- **Proposed default**: "This head is already tilted — usually a head-turn is left
+  out for such a painting. Shall we?"
+
+### P4. The face turns by depth, within a small range
+
+- **Lesson**: a face turns by depth and change of view, within about ±15° left to
+  right and ±12° up and down, and is never rotated flat on the screen.
+- **Why**: beyond that range the painted features have nothing behind them, and a
+  flat spin reads as the picture rotating, not the head.
+- **Waypoint**: `camera_depth`
+- **Proposed default**: "Usually the face turns within about ±15° left-right and
+  ±12° up-down. Shall we?"
+
+### P5. Depth that is there but invisible reads as flat
+
+- **Lesson**: parallax has to be visible at viewing size.
+- **Why**: depth present in the data but spanning only a few pixels across the
+  whole figure reads as flat, however correct it is.
+- **Waypoint**: `camera_depth`
+- **Proposed default**: "Usually the arms visibly lead the body when the view
+  turns. Shall we?"
+
+## For the gates, not the interview
+
+These defects were sent back in review, but nobody would answer "yes" to them, so
+they are never proposed to the user; the user only sees their absence. Each is a
+gate candidate for [rig-c/parts](https://github.com/rig-c/parts), with the bar
+that would catch it. The fix belongs in the rig or its source; a repaint or a
+change of motion is not offered to the user as the way out of a defect.
+
+| # | Defect | Bar that would catch it | Nearest parts check today |
+| --- | --- | --- | --- |
+| G1 | Background showing through the torso in motion ("waist tears"); missed when only a few sampled frames were read | 0 background pixels inside the figure band, counted over **every** frame of the loop, not a sample | partial: `SEAM_OVER_MOTION` is a bar for proven body-root pairs and only a warning for internal-joint and explicit seam pairs; `figure_openings` warns, never refuses |
+| G2 | A seam line and a colour break across a part boundary, and a square notch at a mesh corner (an image stretched into padded UVs, plus a grid corner) | across every part boundary, the colour step is no larger than the painting's own step at the same place; the outline's turn angle is continuous across the boundary | none named |
+| G3 | Kinked folds and a visible seam at rest that the painting does not have, caused by draw order | the setup pose matches the painting within a declared limit, over every part | yes when a limit is declared: `SETUP_MATCHES_PAINTING` (PASS/FAIL, SKIP without a limit); `SETUP_POSE_VS_SOURCE` reports the measurement |
+| G4 | Pinholes inside the figure at rest | 0 transparent openings inside the figure silhouette in the setup pose | not as a bar: `figure_openings` warns; `RECOMPOSITE_HOLES` reports, never fails |
+| G5 | Background plate residue where the figure was removed: a dark silhouette ghost, pale blurred blocks where a structure behind should continue, a smudged emblem, a colour smear | in a band around the figure mask, 0 figure-coloured pixels on the plate, and the fill continues the structure behind it | none — plates are composed outside the current checks |
+| G6 | Plates or character source edited in code (segmentation, patch synthesis, scripted inpainting) instead of in an image editor. One exception: a receipted generative plate pass from a package command is a source, not a repair. It covers only the step-4 background figure-removal plate and the foreground matte, made by the parts plate command with a `rig-parts-plate-receipt/1` receipt and a mask taken from a source, never a hand polygon | every edited image carries an editor receipt, and every step-4 plate pass carries its plate receipt; 0 edits without one | none |
+| G7 | A part carved out of a layer with a hand-drawn polygon instead of taken from the layer split or another real source; such cuts tear at the edge | every part's pixels trace to a layer of the split or to an editor receipt; 0 parts without a source | none |
+| G8 | A paired part split unevenly — one side of a left/right bust, eye, hair end or hem panel missing, much smaller, or cut at a different place — and shown to the user that way | before the split proposal is shown, every pair has both members, comparable area and mirrored edge placement, measured on the parts and compared with the same measure on the painting, so an asymmetry the painting itself has is not flagged | none named |
+| G9 | Specks and holes in the part images straight out of the layer split: loose dots apart from a part, transparent pinholes inside it | on each raw split layer before `assemble`, on a sentinel colour: 0 specks (an 8-connected island of alpha above 8 under 64 px that the painting has no matching content for — outside the silhouette, or not the painting's colour there) and 0 holes (transparent pixels inside the layer's own silhouette), both counts reported per layer; caught at the split, earlier than G4 at rest ([LESSONS.md](LESSONS.md#specks-and-holes-in-the-split-layers)) | none at the split: `assemble` reads only after the merge (`uncovered holes`, and speck counts in its limb-subset `LINT` lines) |
+
+The source gives no numeric threshold for G2, G3, G5 and G8 beyond what is written
+above (G9's 64 px is a pilot measurement, 2026-11-03); where a limit is needed it
+is declared per rig, not assumed.