@punal_manalan/blender-project-harness 0.0.0-stage → 1.0.2

package/.kilo/skills/blender-mcp/references/rigging.md

@@ -0,0 +1,123 @@
+---
+title: Rigging
+summary: Armatures from Python, Rigify for characters, skinning with automatic weights and how to fix it, and verifying deformation.
+---
+
+# Rigging
+
+## Before rigging
+
+- Inspect existing transforms, animation, constraints, and rig conventions before changing them.
+  Applied scale and aligned mesh/rig transforms often help, but world origin, ground placement, and
+  facing -Y are conventions, not universal automatic-weight requirements. Do not move or apply
+  transforms to an existing rig without assessing the impact.
+- Merge duplicate vertices (`bmesh.ops.remove_doubles`) and remove loose parts. Generated meshes
+  are often many disconnected islands, which makes automatic weights fail.
+- Characters rig best in A-pose or T-pose with a bit of bend at elbows and knees.
+
+## Humanoids: Rigify
+
+All operators below MUST follow `bpy.md`: verify required mode, exact targets, and `poll()`;
+use a viewport override only when required. Any actual selection/active-object changes MUST be
+saved and restored in `finally`. Edit bones MUST be accessed only in Edit Mode.
+
+```python
+import addon_utils
+addon_utils.enable("rigify", default_set=False)  # when enabling it is authorized
+bpy.ops.object.armature_human_metarig_add()     # needs a 3D viewport override
+metarig = bpy.context.active_object
+```
+
+1. Scale and move the metarig to fit the mesh (edit bones: `metarig.data.edit_bones["spine"].head`),
+   aligning joints with the mesh's joints. Check against the mesh with `look(mode="angles", shading="xray", views=["front","right"])`.
+2. Generate: with the metarig active, `bpy.ops.pose.rigify_generate()`. Inspect the actual generated
+   rig instead of assuming a fixed name. Preserve the metarig for regeneration.
+3. Skin to the generated rig, not the metarig.
+
+## Simple or non-humanoid rigs
+
+Build bones directly in Edit Mode, starting from Object Mode. This example temporarily changes
+actual selection, so restoration is mandatory even if bone creation fails:
+
+```python
+if bpy.context.mode != "OBJECT":
+    raise RuntimeError("Rig creation requires Object Mode")
+view_layer = bpy.context.view_layer
+saved_selection = [o for o in view_layer.objects if o.select_get()]
+saved_active = view_layer.objects.active
+arm_data = bpy.data.armatures.new("Rig"); rig = bpy.data.objects.new("Rig", arm_data)
+bpy.context.scene.collection.objects.link(rig)
+try:
+    for selected in saved_selection:
+        selected.select_set(False)
+    rig.select_set(True)
+    view_layer.objects.active = rig
+    if not bpy.ops.object.mode_set.poll():
+        raise RuntimeError("Cannot enter Edit Mode for the new rig")
+    try:
+        bpy.ops.object.mode_set(mode="EDIT")
+        root = arm_data.edit_bones.new("root"); root.head = (0, 0, 0); root.tail = (0, 0.3, 0)
+        b = arm_data.edit_bones.new("arm"); b.head = (0, 0, 1); b.tail = (0, 0, 2); b.parent = root
+    finally:
+        if rig.mode != "OBJECT":
+            if not bpy.ops.object.mode_set.poll():
+                raise RuntimeError("Cannot leave Edit Mode; stop and report the current state")
+            bpy.ops.object.mode_set(mode="OBJECT")
+finally:
+    rig.select_set(False)
+    for selected in saved_selection:
+        selected.select_set(True)
+    view_layer.objects.active = saved_active
+```
+
+Mechanical things (doors, wheels, robots) often suit rigid bone parenting. Set the parent, bone, and
+parent inverse while preserving the intended world transform; direct parent assignment can move parts.
+
+## Skinning
+
+For automatic weights, MUST isolate the intended mesh and armature, with the armature active.
+This override leaves actual user selection unchanged; selecting the mesh alone would retain
+unrelated selected objects and can reparent them:
+
+```python
+if bpy.context.mode != "OBJECT" or mesh.type != "MESH" or rig.type != "ARMATURE":
+    raise RuntimeError("Automatic weights require Object Mode, a mesh, and an armature")
+targets = [mesh, rig]
+if any(o not in bpy.context.editable_objects or o not in bpy.context.selectable_objects
+       for o in targets):
+    raise RuntimeError("Skinning targets must be editable and selectable")
+with bpy.context.temp_override(object=rig, active_object=rig,
+                               selected_objects=targets, selected_editable_objects=targets):
+    if not bpy.ops.object.parent_set.poll():
+        raise RuntimeError("parent_set is unavailable in this context")
+    bpy.ops.object.parent_set(type="ARMATURE_AUTO")
+```
+
+If Blender reports "Bone Heat Weighting: failed to find solution for one or more bones":
+
+- Merge by distance and remove interior faces, then retry.
+- Or skin a voxel-remeshed copy, then transfer weights to the original with a Data Transfer
+  modifier (vertex groups, nearest face interpolated) and apply it.
+- If scale contributes to failure, test larger scale on a copy while preserving transforms and rig
+  relationships; do not rescale the original rig as a blind repair.
+
+## Verify
+
+`get_scene_info(fields=["weights"], query="Body")` reports vertices no deform bone moves and deform
+bones with no vertex group. Investigate unweighted vertices and unused groups against the intended
+deformation; intentionally unused deform bones are possible. Save existing pose transforms before
+testing a rig control whose actual name was inspected:
+
+```python
+pb = rig.pose.bones["upper_arm_fk.L"]; pb.rotation_mode = "XYZ"; pb.rotation_euler.x = 1.2
+```
+
+`look(mode="angles", target=["Body"])` and check elbows, shoulders, knees and hips for collapsing
+or stretching. Restore the saved pose transforms afterward; do not clear the user's original pose.
+
+## Sources
+
+- https://docs.blender.org/manual/en/5.0/addons/rigging/rigify/introduction.html
+- https://docs.blender.org/manual/en/5.0/addons/rigging/rigify/basics.html
+- https://docs.blender.org/api/current/info_gotchas_armatures_and_bones.html
+- https://raw.githubusercontent.com/blender/blender/v5.0.0/source/blender/editors/object/object_relations.cc

package/.kilo/skills/blender-mcp/references/scene.md

@@ -0,0 +1,72 @@
+---
+title: Scene design
+summary: Building a believable scene - scale, grounding, composition, choosing between generated and library assets, lighting and camera.
+---
+
+# Scene design
+
+## Workflow
+
+1. `get_scene_info` — know what's there and the scene's scale before adding anything.
+2. Block out with primitives at real-world size: the layout, the big shapes, the camera.
+   `look(mode="camera")` or `look(mode="angles")` to check proportions before spending on assets.
+   Use `text` for labels and `modifier` for bevel, subdivision, solidify, mirror, and array detail.
+3. Replace blockout pieces with real assets, biggest and most visible first.
+4. Light, then set materials, then dress with small props.
+5. Judge the image, not your intentions: is anything
+   floating, clipping, the wrong size, or hidden from camera?
+
+## Getting assets
+
+MUST read [`blender-assets`](../../blender-assets/SKILL.md) before external asset work and follow
+the asset-type branches in `../SKILL.md`. Model size/support checks below do not apply to HDRI
+worlds or texture materials; those require lighting/material inspection instead.
+
+- **Import locally** with the harness `import_asset` operation after the file is registered under
+  `assets/external/<source>/<asset>/`; use `link_library` for `.blend` libraries. Use
+  `blender_workflow {action:"intake"}` to copy user files and create the register and sidecars. The
+  raw `blender_import_asset` and `blender_generate_3d` tools stay blocked.
+- **Poly Haven** (`search_assets(source="polyhaven")`): HDRIs, PBR textures for large surfaces
+  (floors, walls, terrain), and generic realistic props. CC0.
+- **Sketchfab**: specific real-world things (a named car model, a landmark), and realistic props.
+  Check the licence and face count in results.
+- **Poly Pizza**: stylised low-poly props, fast and light. Credit CC-BY creators.
+- **Script it** only through reviewed harness operations; arbitrary project Python is blocked.
+
+Match the confirmed style. Mixed low-poly and photoreal assets can be intentional; do not impose a
+style restriction that the user has not confirmed.
+
+## After every model import
+
+Imported models arrive at arbitrary scale, rotation and origin. Inspect the imported parent or child
+bounds with `get_scene_info`; use those facts:
+
+- Scale to real size from the bounding box, not by eye.
+- Place it on its intended support surface. For an unparented object on world Z=0,
+  `obj.location.z -= min_z` uses the world bounding box minimum. Account for parent transforms.
+- Rotate it to face the right way; generators usually face -Y or +Y. Check with
+  `look(mode="angles", target=[name])`.
+- Check it doesn't intersect its neighbours.
+
+## Composition
+
+- Decide the camera early and compose for it; set `scene.camera`, focal length 35–50 mm for
+  natural views, 85 mm+ for product shots, 24 mm or wider for interiors.
+- Foreground, midground, background. Leave negative space. Rule of thirds for the subject.
+- Vary scale and rotation of repeated props slightly; perfect grids read as fake.
+- Ground contact sells realism: props sit on surfaces, small things cluster against larger ones.
+
+## Lighting
+
+- Start with an HDRI from Poly Haven for ambient light and reflections; set its strength
+  (0.5–1.5), then add a key light (sun or area) for shape and shadows.
+- Three-point for products: key, fill at lower power, rim behind.
+- Interiors: area lights in windows (portals in Cycles) plus practicals (lamps with emission).
+- Check with `look(mode="camera", shading="rendered")` for EEVEE or Workbench. For Cycles, render
+  and inspect `look(image="Render Result")`. Investigate exposure, lighting, materials, and intended
+  contrast instead of treating every black or white area as a lighting error.
+
+## Render settings
+
+Read the current engine rather than setting one blindly (see `bpy.md`). For quick
+previews keep samples low; raise them only for the final render.

package/.kilo/skills/blender-project-goal/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: blender-project-goal
+description: Use for Blender design requests and returns to paused projects. Defines discovery, bootstrap, project goal recording, and goal start/resume. Excludes read-only questions and workspace maintenance.
+---
+
+# Blender Project Goal
+
+Blender production requires an active registered goal and current project records. Read-only
+questions and workspace maintenance MUST NOT launch or modify Blender.
+
+The orchestrator owns goal commands and continuation decisions. Users provide inputs, never goal
+commands. If the goal is already paused, do not repeat the stop procedure. There is no successful action, final response, or runtime notice that is approval. A final response alone does not prove approval; a response is not approval without the runtime receipt.
+
+Use `blender_document` `{action:"read"}` for structured project-document access; direct full-file
+reads are acceptable but discouraged. Use `blender_workflow {action:"status"}` after compaction,
+restart, or any gate error. Execute `status.nextStep.command`; it names the required goal, document,
+registration, launch, or production step. The canonical goal template is
+`../../../.kilo/blender-project-harness/tools/harness/templates/project/Documents/Goals/01-project-brief.md`.
+
+## New project
+
+Requirements, workflow mode, review mode, and scaffolding happen in ordinary chat before a goal
+starts. Kilo removes `question` during an active goal.
+
+1. Confirm requirements with `blender-project-requirements`.
+2. Ask the optional-workflow intake questions: generate references with Media MCP or supply them,
+   use supplied, direct-download, browser/provider, or user-assisted assets, handle scripts as
+   none/source-only, and required deliverable formats. Use `intake {scan:true}` to inspect supplied
+   paths; it does not write the project. Do not generate paid images, download, or execute scripts
+   without explicit consent. Record the media/download scope in the goal or decisions.
+3. Collect workflow mode with `blender-project-workflow` and review mode with
+   `blender-project-grading`.
+4. Scaffold with `blender-project-scaffold`.
+5. Create or update README, requirements, workflow, review, assets, decisions, and the filled goal
+   with `bootstrap-document`. Use `capabilities.documentFormats`; the harness rejects malformed
+   records.
+6. Commit the exact scaffold with `bootstrap-commit`. NEVER stage or commit project paths manually.
+7. Call `prepare` `{project,goal,scene}`. Pass its exact question and labels to `question`. Only the
+   runtime answer registers the project.
+8. Call `goal(action="start", objective=<the entire filled prompt>)`. End the turn after a
+   successful start.
+9. On the next goal turn, inspect `blender_workflow` `status` and continue with its `nextStep`.
+
+NEVER start a goal to ask questions. NEVER create new project documents outside the harness. Update
+existing documents only inside declared change paths.
+
+## Return to paused project
+
+1. Read `Documents/WORKFLOW.md`, `Documents/REVIEW.md`, the active goal, requirements, assets, and
+   decisions needed for the pending work.
+2. On a genuine later return, ask both mode questions only before registration. Once registered,
+   requirements, workflow, review mode, and the active goal are frozen; do not reask or record a mode
+   change inside the run. Routine approval, clarification, manual-edit pauses, automatic goal turns,
+   and compaction are continuations: do not reask modes for those.
+3. Confirm records remain current. Registration-changing edits require supported re-registration
+   through `prepare`; current re-registration is limited to the capped-review escalation path. If the
+   required path is unavailable, STOP and report the tooling blocker. Never edit external harness
+   state.
+4. Resume only when the pending answer permits continuation:
+   `goal(action="resume")` for an unchanged objective. End the turn.
+5. Changed scope MUST stop production and report the need for explicit re-registration. Do not edit
+   the active goal or other registration documents inside a change. NEVER resume a stale objective.
+
+## Required goal content
+
+The filled goal MUST contain:
+
+- Mission in the user's exact words.
+- Project name and links to README, requirements, workflow, review, assets, decisions, and
+  references.
+- Visual outcome: subject, composition, camera, lighting, materials, colour, scale, mood.
+- Scope: in, out, external dependencies.
+- Deliverables: scene, review render, exports, documents.
+- Acceptance checks observable in a render or readable in a file.
+- Workflow: harness actions, autonomy mode, review mode, configured graders.
+- Done: current documents, inspected sealed render, final applicable `PASS` when grading is enabled,
+  and no genuine unresolved blocker or major finding.
+
+## Goal state
+
+Kilo stores the goal under session metadata `kilo.goal` with status `active`, `paused`, `blocked`, or
+`complete`. A rejected tool call blocks the goal; `goal_report` is unavailable until
+`goal {action:"resume"}` succeeds. The harness exposes `status.kiloGoal` and, when Kilo reports
+`blocked` or `paused`, returns `nextStep.phase:"resume-goal"`. Follow it before any report or further
+production action. A harness deny is not permission to bypass the gate.
+
+## Input handoffs
+
+Kilo has no `question` during an active goal.
+
+1. If work cannot continue because approval or a decision is missing, call
+   `goal_report(status="blocked", reason=<pending input>)` with the exact evidence. A blocked report
+   does not require a commit. End the turn with the decision needed and the next change proposed for
+   the user.
+2. On the next ordinary user turn, ask the required `question` before resuming.
+3. For approval, call `blender_workflow` `approval` and use its exact question and labels. Freeform
+   direction does not replace the runtime receipt.
+4. Resume with `goal(action="resume")` only after the answer authorizes continuation and records
+   remain current. End the turn.
+5. NEVER delegate goal commands to the user, self-approve, or resume an outdated goal.
+
+## Rules
+
+- Production MUST NOT start before registration, active goal, and committed valid records.
+- Requirements are frozen after registration; a requested change stops production for explicit
+  re-registration.
+- Partially Autonomous approval is mandatory after every reviewable change before its commit.
+- `review` mode `All` or `Single` requires configured grader receipts before approval or commit.
+- Use harness document and commit actions. Manual project document writes and Git commits are
+  blocked.
+- Unsupported material is not made acceptable by a written goal. Stop for reviewed tooling.
+- NEVER claim completion without a clean checkpoint, inspected sealed render, and final applicable
+  `PASS` or recorded `Off` self-review. Call `goal_report(status="complete",reason=<evidence>)` only
+  after that state; then give the final response. Stop Blender through `blender_workflow` unless it
+  is intentionally left open for user inspection, and report which choice was made.

package/.kilo/skills/blender-project-grading/SKILL.md

@@ -0,0 +1,184 @@
+---
+name: blender-project-grading
+description: Use when configuring or running independent Blender grader subagents. Defines review modes, evidence, round folders, aggregation, dispositions, and re-review.
+---
+
+# Blender Project Grading
+
+Graders review sealed evidence against confirmed requirements. They do not edit the scene and do not
+replace the orchestrator's mandatory `blender_look` inspection.
+
+`AGENTS.md` defines hard invariants. `blender-workflow-harness` defines the runtime actions. Call
+`blender_workflow {action:"status"}` and follow `nextStep` when a review gate fails.
+
+## When review is required
+
+- Review every reviewable change: a bounded change with at least one apply operation.
+- NEVER review the bootstrap save. Commit and checkpoint it without sealing or grading.
+- Mode `Off`: call `self-review` after inspecting the sealed render.
+- Mode `All`: every configured grader reviews each round.
+- Mode `Single`: only the named configured grader reviews.
+- Partially Autonomous: complete review and obtain approval before the change commit.
+- Re-review a failed round with `revision:true` within `max_rounds`.
+- Missing, disabled, invalid, or unavailable required grading STOPS production. NEVER silently
+  downgrade to self-review.
+
+## Milestone scope
+
+- `final:false` is a partial milestone. Graders must judge only the declared milestone and the
+  requirements it advances. Future or unbuilt scope is deferred, not a finding; absent future content
+  MUST NOT be reported as a blocker or major.
+- `final:true` is the full-spec review. Only then must every confirmed requirement and the complete
+  deliverable be present.
+- For intermediate changes, pass the milestone-specific requirement IDs the change advances. Do not
+  pass full-deliverable IDs whose content is intentionally deferred; reserve the complete set for the
+  final change.
+- The grader ticket prompt includes the partial/final scope contract. Do not remove or weaken it.
+
+## Review mode record
+
+`Documents/REVIEW.md` MUST contain one `Mode:` value (`Off`, `All`, or `Single`), one `Selected:`
+date, and for `Single` one `Single grader:` name. Ask the mode in ordinary chat before the goal
+starts and on a genuine later return. Do not reask for routine approval or continuation pauses.
+Switch modes only after explicit user direction. After registration, the review record is frozen;
+stop and report the need for explicit re-registration instead of editing it inside a bounded change.
+
+## Config
+
+Read `blender_subagents.graders` from `.kilo/blender-project-harness/config.json`. The tracked
+`.kilo/blender-project-harness/config.example.json` is the template.
+
+```json
+{
+  "blender_subagents": {
+    "graders": {
+      "agent": "blender-grader",
+      "enabled": true,
+      "max_parallel": 1,
+      "max_rounds": 2,
+      "graders": [
+        {
+          "name": "visual",
+          "focus": "composition, camera, lighting, colour, materials",
+          "provider": "provider-id",
+          "model": "model-name",
+          "variant": "reasoning-variant",
+          "backup": {
+            "provider": "backup-provider-id",
+            "model": "backup-model-name",
+            "variant": "backup-reasoning-variant"
+          },
+          "max_minutes": 5,
+          "max_steps": 10
+        }
+      ]
+    }
+  }
+}
+```
+
+The harness validates the roster at `prepare`: unique slug, non-empty focus/model fields, one complete
+backup provider/model/reasoning variant per grader, positive budgets, `max_steps` within the grader
+ceiling, `max_parallel` within the roster, and `max_rounds` 1-4. Give the `spec` grader 12 steps when
+it must complete a final full-spec review; 10 can be exhausted before the documentation reads. NEVER fabricate, drop, substitute, or
+borrow a grader or model. Resolve models with `agent_manager_models`; per-task overrides require
+explicit user request. A primary dispatch failure may retry once with the configured backup; record
+`modelRole` and do not change the roster or review mode.
+
+## Evidence and round folder
+
+For every scene change, call `finalize`, then issue `wip`, and `blender_look` the WIP render before
+`seal`; every third apply also requires a WIP check. A WIP render is not review evidence and stays
+out of commits.
+
+Call `seal` after the reviewable scene is ready. It saves the authoritative scene and captures every
+declared scene:
+
+- a camera PNG per scene (and a master sequence still when applicable);
+- `scene.txt` and `scene-facts.json` per scene;
+- `manifest.json` with UTC time, goal, base commit, dirty state, primary scene, scene list, scene
+  requirement mapping, spec hashes, selected graders, and evidence hashes.
+
+Call `blender_look` on every returned scene render. The runtime records one inspection receipt per
+scene; review is blocked until every declared scene is inspected. NEVER substitute an image, rewrite
+sealed evidence, or change the manifest.
+
+The harness creates `Documents/Reviews/R<NN>-<yyyyMMddTHHmmssZ>/`. `NN` is the next project-wide round number; never reuse or overwrite a round. `_evidence/` is ignored; reports, manifest, and the round index are tracked. Each grader writes only `<grader>/REPORT.md`, through `blender_document` `{action:"write"}`. Direct report edits are denied. The ticket prompt lists exact evidence files with hashes; the grader must read those exact paths, not an evidence folder, and may use only its assigned report. A multi-scene report must cite every declared scene name. Read `operation_tasks` in the manifest and `Documents/TASKSTRACKER.md` with `Documents/Tasks/<id>/` as process evidence; `blender_document {action:"ledger"}` returns the structured rows. Never edit either.
+
+## Dispatch
+
+0. Read spec documents through `blender_document` `{action:"read"}`. Direct `read`/`grep` is
+   acceptable but discouraged. Read non-markdown evidence directly.
+
+1. After seal and successful `look`, call
+   `blender_workflow` `grader-ticket` `{name}` for each selected grader.
+2. Pass its returned prompt to the normal `blender-grader` task. Keep the literal
+   `HARNESS_GRADER:<token>`, report path, scene hash, evidence key, and deadline unchanged.
+3. Fill only the user-prompt and prior-findings placeholders. Do not invent a child session or
+   report receipt.
+4. Issue all selected grader tickets, then dispatch up to `max_parallel` grader tasks in one batch
+   before waiting; graders run read-only and never edit the scene. One writer rule remains.
+5. Retain each runtime-bound `task_id`. Resume the same grader session for re-review when model and
+   focus are unchanged.
+6. If a task fails before binding a child session, call `grader-fail {name,reason}` so the failure
+   is recorded against the ticket.
+
+A missing or failed report permits one replacement `grader-ticket` before `review`; the replacement
+gets a fresh pass budget. A tooling/evidence `BLOCKED` report is retryable without a scene revision;
+a second failure is aggregated by `review`, after which `nextStep` returns `retry-grader` or
+`preserve`, not `begin`. Graders never loop or ask the user. The assigned report write is exempt
+from both the step budget and the deadline so a grader can always record its verdict. A grader may
+read its own prior `REPORT.md` under `Documents/Reviews/`; peer grader reports remain denied.
+
+## Aggregate and dispose
+
+1. Verify each report exists, cites the sealed evidence and scene hash, and declares exactly one
+   verdict.
+2. Merge duplicate findings; the highest substantiated severity wins.
+3. Resolve disagreements against the confirmed spec and frozen evidence; record the reasoning.
+4. Record every finding as `open`, `fixed`, `deferred`, or `declined` with a reason. A declined
+   blocker or major requires evidence that it is false or outside confirmed scope. Time pressure or
+   preference is not a waiver.
+5. Call `review` `{notes,reason,dispositions}`. The harness validates reports, computes the verdict,
+   writes `REVIEW.md`, appends the round row to `Documents/Reviews/README.md`, and auto-commits in
+   Fully Autonomous mode. In Partially Autonomous mode it
+   writes the verdict and waits for approval; `commit` then creates the review commit. A tooling
+   `BLOCKED` verdict is not auto-committed; retry the blocked grader with the configured backup.
+6. After the retry budget is exhausted, call `preserve {reason}` instead of looping. It commits the
+   sealed render, reports, aggregate review, tracker, and task records as `WIP`; then `checkpoint`
+   and `pause` or `reregister`. NEVER mark a tooling block `PASS`.
+7. Call `checkpoint` after the scoped commit. NEVER create or commit review documents manually.
+
+Verdicts:
+
+- `PASS`: all selected graders completed, required dimensions were assessed, evidence is complete,
+  and no substantiated blocker or major remains.
+- `CHANGES_REQUIRED`: at least one blocker or major remains.
+- `BLOCKED`: evidence/spec missing, grader failed, or a necessary decision is unavailable.
+
+One substantiated blocker fails the round regardless of other PASS verdicts. Two rounds without
+improvement on the same finding STOP for user direction; do not run a third automatic round.
+
+## Re-review
+
+Create a new round with `revision:true`. Resume the same grader sessions where possible. Give each
+grader its own prior report path, the new frozen evidence, the new exact report path, and the
+orchestrator's dispositions. The grader marks each prior finding `FIXED`, `OPEN`, or `REGRESSED`
+with evidence, then adds new findings. NEVER permit peer report reads or rewrite sealed metadata.
+
+## Approval and completion
+
+- In Partially Autonomous mode, complete review before calling `approval`. Pass its exact question
+  and labels to `question`; only a runtime answer authorizes the commit.
+- Findings do not authorize fixes. A correction requires a new bounded `begin` with `revision:true`.
+- Completion requires a clean `checkpoint`, current records, inspected sealed render, and final
+  applicable `PASS` or recorded `Off` self-review with no unresolved blocker or major.
+- Commit policy: `bootstrap-commit` before registration, `commit` after registration. Manual project
+  Git commands are blocked. Failed/expired changes use `recover` for repairs or `commit {mode:"wip"}`
+  to preserve them; a sealed tooling block uses `preserve`. `checkpoint` verifies exactly one scoped
+  commit range after the change base and a clean project.
+
+## References
+
+- `.kilo/agent/blender-grader.md` for the report rubric and output contract.
+- `.kilo/blender-project-harness/config.example.json` for the tracked config template.

package/.kilo/skills/blender-project-readme/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: blender-project-readme
+description: Use when creating or updating a Blender project README. Enforces the required project sections and harness-owned document path.
+---
+
+# Blender Project README
+
+Canonical template: `../../../.kilo/blender-project-harness/tools/harness/templates/project/README.md`. Write the project copy
+at `Blender/<Project>/README.md` through `bootstrap-document` before registration or `document`
+inside a declared bounded change.
+
+## Required sections
+
+Keep this order. Each heading MUST appear exactly once.
+
+1. Project title.
+2. Purpose: one concrete paragraph.
+3. What this project is: subject, audience, visual result.
+4. Requirements: link to confirmed `Documents/REQUIREMENTS.md`; summarize only the highest-priority
+   points. Do not duplicate the requirement register.
+5. Visual direction: style, references, colour, lighting, camera, scale.
+6. Deliverables: main `.blend`, final renders, exports, documents.
+7. Project structure: actual folders and authoritative `.blend`.
+8. Blender: workspace MCP port, harness launch/stop, run log, main file, relative paths, one-instance
+   rule.
+9. Workflow: links to `Documents/WORKFLOW.md` and `Documents/REVIEW.md`; selected modes; review index.
+10. External assets: summary plus links to `Documents/ASSETS.md` and
+    `assets/external/README.md`. User files are brought in through `intake`; never instruct the user
+    to create folders or copy by hand.
+11. Goals: index of `Documents/Goals/*.md`.
+12. References: links to `Documents/References/`.
+13. Open questions and next steps.
+
+The harness validates `Status:` and `Last updated:` fields. Replace instructional placeholders with
+project facts. Do not invent requirements or asset details; link to their registers.
+
+## Validation
+
+- Every deliverable path MUST exist or be explicitly planned.
+- Requirements MUST be confirmed and linked.
+- Workflow and review records MUST contain selected modes and be linked.
+- The authoritative `.blend` path MUST match the MCP settings after the first save.
+- External assets MUST be registered and linked.
+- The goal index MUST match `Documents/Goals/` and identify the active goal.
+- Before completion, the README MUST reflect the delivered state, inspected review render, and final
+  applicable review result.

package/.kilo/skills/blender-project-requirements/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: blender-project-requirements
+description: Use before creating a Blender project and whenever requirements are added or changed. Runs a confirmation discussion and stores confirmed requirements.
+---
+
+# Blender Project Requirements
+
+Requirements are agreed with the user, never inferred. Production MUST NOT start until requirements
+are confirmed, workflow and review modes are selected, the scaffold is committed, and registration is
+complete.
+
+## Gate
+
+- Run this discussion in ordinary chat before any goal starts. Kilo removes `question` during an
+  active goal.
+- Do not scaffold, launch Blender, or create scene work during the discussion.
+- For a necessary question during production, follow `blender-project-goal` for the required-input
+  handoff. Do not let an unconfirmed requirement become scene work.
+- Pure workspace maintenance is exempt.
+
+## Discussion
+
+1. Read `AGENTS.md` and the existing project documents.
+2. Use the user's request as the starting brief. Ask only for information that is missing.
+3. Use `question` for concrete choices, ambiguities, visual direction, scope, constraints, external
+   assets, and acceptance. Keep options to 2-4.
+4. Challenge vague terms. Convert abstract ideas into observable outcomes. Put future work under
+   `Deferred` and explicit exclusions under `Out of scope`.
+5. Cover purpose, audience, visual outcome, deliverables, acceptance, constraints, external assets,
+   and exclusions. Do not walk a generic checklist.
+6. Reflect a concise draft back to the user. Ask:
+   - `Confirm requirements`
+   - `Keep discussing`
+   - `Change something`
+7. Loop until the user explicitly confirms. Silence, a new topic, or an unrelated `ok` is not
+   confirmation.
+8. On confirmation, record the exact user words and scope. Create or update
+   `Documents/REQUIREMENTS.md` with `Status: Confirmed`, `Confirmed: YYYY-MM-DD`,
+   `Confirmation: <exact response and scope>`, and a change-log row. Use `bootstrap-document` before
+   registration. After registration, requirements are frozen; do not use `document` for them.
+9. New project: collect workflow mode with `blender-project-workflow` and review mode with
+   `blender-project-grading`, scaffold, fill all records, commit with `bootstrap-commit`, then
+   `prepare` and start the goal.
+10. Existing project: registration documents are frozen after registration. If the user requests a
+    requirements change, STOP and report the need for explicit re-registration. Do not edit
+    `Documents/REQUIREMENTS.md`, `Documents/WORKFLOW.md`, `Documents/REVIEW.md`, or the active goal
+    inside a bounded change.
+
+## Research
+
+- Use `websearch` for ambiguous terms, current standards, references, feasibility, or best practice.
+- Use Context7 for library, framework, and Blender API docs. Follow `blender-mcp` for Blender API
+  gaps.
+- Research factual gaps before asking; ask the user for preference, intent, priority, or scope.
+- Use official or primary sources first. State date, version, and conflicts.
+- Report a short `found / means / options` summary with titles and URLs. Separate facts from
+  assumptions.
+- Record research that supports or changes a requirement under `Research notes`; put long material
+  in `Documents/References/`. NEVER turn a finding into a requirement without explicit confirmation.
+- If research is unavailable or inconclusive, mark an open question. Do not guess.
+- Search public information only. NEVER send private project data, credentials, or user identity.
+
+## Requirement format
+
+- Use stable IDs grouped by category: `REQ-01`, `REQ-02`, and so on.
+- Make each requirement testable and user-visible where possible.
+- Keep unresolved items under `Open questions` and acknowledged future work under `Deferred`.
+- Keep explicit exclusions under `Out of scope` with a reason.
+- Store the confirmed source in `Documents/REQUIREMENTS.md`; do not duplicate it across documents.
+
+## Mandatory record
+
+The harness validates `Documents/REQUIREMENTS.md` through `capabilities.documentFormats`. It MUST
+contain exactly the required fields and sections, including:
+
+- `Status: Confirmed`
+- a valid `Confirmed:` date
+- a non-placeholder `Confirmation:` reply
+- `Core value`, `Confirmed requirements`, `Constraints`, `Deferred`, `Out of scope`,
+  `Open questions`, `Research notes`, and `Change log`
+
+A malformed or unconfirmed record blocks `prepare`. Fix it through `bootstrap-document` before
+registration; never edit around the harness. After registration, stop and report the malformed
+record instead of writing the frozen document.