Skel: Slice J — CLI/MCP parity, docs, tests

[fernandotonon]

Parent epic: #554
Depends on: Slices A–I (functionally needs A, B, C, D, F minimum)

Goal

Bring skeletal rigging to project conventions: CLI, MCP, breadcrumbs, tests, docs.

Scope

• CLI — new qtmesh rig subcommand:
  • qtmesh rig model.fbx --add-bone <name> --parent <parent> --pos x,y,z -o out.fbx
  • qtmesh rig model.fbx --remove-bone <name> [--transfer-weights] -o out.fbx
  • qtmesh rig model.fbx --rename-bone <old> <new> -o out.fbx
  • qtmesh rig model.fbx --reparent <bone> <new-parent> [--keep-world|--keep-local] -o out.fbx
  • qtmesh rig model.fbx --attach-bone <bone> --to <target.fbx> -o target-out.fbx
  • qtmesh rig model.fbx --capture-rest-pose --animation <anim> --time <t> -o out.fbx
  • qtmesh rig model.fbx --paint-weight <bone> --json-strokes <strokes.json> -o out.fbx (offline weight paint via stroke description; ambitious — verify before committing)
  • qtmesh rig model.fbx --mirror-weights --axis x [--naming <regex-pair>] -o out.fbx
  • qtmesh rig model.fbx --normalize-weights -o out.fbx
  • qtmesh rig model.fbx --limit-weights <N> -o out.fbx
  • qtmesh rig model.fbx --ik-create --chain <bone1>,<bone2>,<bone3> --target <target-node> -o out.fbx
  • qtmesh rig model.fbx --ik-bake -o out.fbx
  • qtmesh rig model.fbx --constraint-add <bone> --type look-at --target <node> -o out.fbx
  • qtmesh rig model.fbx --list-bones [--json] — already exists in some form via info; verify and consolidate.
• MCP tools mirroring each CLI surface:
  • add_bone, remove_bone, rename_bone, reparent_bone, attach_bone_to_entity, duplicate_bone
  • capture_rest_pose, reset_rest_pose, snap_bones_to_pose
  • paint_skin_weight, mirror_skin_weight, normalize_weights, smooth_weights, limit_weights
  • create_ik_chain, bake_ik_to_fk, set_bone_constraint
  • set_bone_display, add_bone_group, set_bone_layer
  • JSON-RPC on main thread via QSocketNotifier. No BlockingQueuedConnection.
• Sentry breadcrumbs (consolidated): scene.skel.bone.*, scene.skel.hier.*, scene.skel.rest_pose.*, scene.skel.weight.*, scene.skel.mirror.*, scene.skel.ik.*, scene.skel.display.*, scene.skel.constraint.*, scene.skel.envelope.*. ui.action for menu/toolbar clicks.
• Tests:
  • SkeletonEditor_test.cpp — CRUD on fixture skeletons.
  • SkinWeightController_test.cpp — normalize, mirror, smooth, limit.
  • IKChainController_test.cpp — 2-bone solver math + bake.
  • PoseMirror_test.cpp — all four naming conventions + mirror op.
  • BoneConstraintEngine_test.cpp — each constraint type (coordinated with Anim: Slice H — Constraints (look-at, IK targets, parent-of, copy-rotation) #525).
  • All headless-CI safe.
• Docs:
  • New "Skeletal Rigging" section in CLAUDE.md under Architecture covering: bone CRUD, hierarchy, rest pose, weight paint, mirror conventions, IK, constraints, display, envelopes.
  • Add qtmesh rig examples to the CLI block.
  • Document on-disk project storage of rig metadata (groups, layers, display shapes, constraints, IK).
  • User-facing changelog: "QtMeshEditor now edits rigs: create/remove/rename bones, paint skin weights, author IK chains and constraints, customise bone display."

Acceptance Criteria

• Every CLI subcommand listed works and supports --json where applicable.
• Every MCP tool works via stdio + HTTP.
• CLI ↔ GUI ↔ MCP parity for every scriptable rig operation.
• Breadcrumbs emitted for every user-visible rig action.
• All listed test files exist and pass on Linux / macOS / Windows CI.
• CLAUDE.md Skeletal Rigging section rewritten and accurate.

Effort

~6 days.