v1.2.4 — PNG→WebP (99% size reduction) + README polish

Asset compression and README polish — both based on direct user feedback ("what about webp instead of png and what about the readme").

Asset compression

Converted all 28 validation proof renders from PNG to WebP at quality 85.

Metric	Before	After	Δ
Total assets size	21.58 MB	0.25 MB	−99%
Files	28 PNGs	28 WebPs	(1:1)
Visual quality at q=85	—	essentially identical	verified across multiple test renders

Updated all markdown asset references (*_attempt*.png, *_FINAL_*.png, etc.) to .webp. Deliberately left untouched: example user invocations (/wireframe-to-3d ./glasses_front.png), ffmpeg output patterns (-i frame_%04d.png), file format spec text, and .gitignore patterns inside knowledge docs.

.gitignore updated: *.webp added to the generated-files block plus the !plugin/skills/**/assets/**/*.webp exception so validation proofs continue to track.

README polish

Several long-standing staleness issues fixed:

• Version line: bumped from "1.0.0" → "1.2.4"
• "What works (honestly)" table: 3 validated scene classes → 6 (added aviator, desk lamp, broadcaster avatar); 4 dimension reference categories → 7; added rows for emission + practical lighting recipes (v1.1.0), volume-absorption coloured glass (v0.7.0), trigger-eval results (100% TP / 4% FP from v1.0.1)
• "What doesn't work yet" section: added human-faces-from-primitives entry pointing at v1.2.1's three escape paths
• "Honest status" section: "9 versions of patches" → "15+"; added pointer to the cheap-tester / expensive-patcher loop documented in docs/process/TESTING_PLAN.md
• Quick links navigation: added at top so readers can jump to install / works / doesn't-work / contributing / releases

This is structural housekeeping. No skill code changed.

v1.2.3 — Repo hygiene reorg + .github scaffolding

Cleaned up top-level clutter and added the standard .github/ files for proper open-source project hygiene.

Top-level reorg

The root went from 14 .md files to 4. Process docs and test results moved to logical subdirectories.

Top-level after (canonical files only):

• README.md
• CHANGELOG.md
• VERSIONING.md
• LICENSE
• requirements.txt
• .gitignore

Moved to docs/process/ (dev journals): PLAN, DEVELOPMENT, TESTING_PLAN, IMPLEMENTATION_LOG, VERIFICATION_REPORT, MCP_COVERAGE_ASSESSMENT, BLENDER_TOOLKIT_COMPARISON, INSTALL_BLENDER_MCP.

Moved to docs/test-results/: test.md, test_round2.md, test_round3.md.

git mv preserves blame history.

.github/ added

• CONTRIBUTING.md — bug + feature workflow, the project's honesty principle, semver
• ISSUE_TEMPLATE/bug_report.yml — structured form (Blender version, OS, mcp version, skill version, failure type, prompt, what happened vs expected)
• ISSUE_TEMPLATE/feature_request.yml — structured form (change type, description, motivation, optional draft recipe)
• ISSUE_TEMPLATE/config.yml — disables blank issues; links to discussions and upstream ahujasid/blender-mcp for MCP-server bugs

Repo hygiene status after this release

• ✓ LICENSE present (v1.2.2)
• ✓ Description, topics, homepage set on GitHub (v1.2.2)
• ✓ Formal release pages for v1.0+ tags (v1.2.2)
• ✓ Top-level uncluttered (this release)
• ✓ .github/CONTRIBUTING + ISSUE_TEMPLATE present (this release)
• ✓ .gitignore covers Python/Blender/IDE/OS junk
• ✓ Largest tracked files are validation proof renders (intentional)

This is structural housekeeping. No skill code changed.

v1.2.2 — Repo housekeeping: LICENSE, metadata, formal releases

Housekeeping pass — making the repo properly discoverable and legally clear.

Changes

• LICENSE added (MIT) — the README has claimed MIT since v0.3.0, but the actual LICENSE file was missing
• Repo description set on GitHub
• Topics added: claude-code, claude-skill, blender, blender-mcp, blender-python, 3d-modeling, mcp, ai-3d, procedural-modeling, gltf
• Homepage URL set to the README
• Formal GitHub Releases created for v1.0.0, v1.1.0, v1.2.0, v1.2.1 (each with curated release notes — not just auto-generated tag pages)

Why

A repo with empty description, no topics, and no LICENSE is hard to find via GitHub search and legally ambiguous to use. Previous tags (v0.x and v1.0–v1.2.1) existed as commit references but didn't appear in the GitHub Releases sidebar. This release closes those gaps.

Functional content unchanged

No skill code changed in this release. The plugin behaviour at v1.2.2 is identical to v1.2.1.

v1.2.1 — Human-from-primitives hard limit; three escape paths

User feedback on v1.2.0 broadcaster: 'does not even close resemble a human.' Accurate.

Tried adding facial features (cube nose, sphere ears, line mouth, bar brows) to the v1.2.0 broadcaster head. Result: still doesn't look human. Documented as a hard limit with three concrete escape paths.

The hard limit

Real human faces are subtractive — eye sockets recessed into the head, cheekbones pulled out, lip curvature, jaw shape. None of that can be added as floating primitives stuck onto a sphere; it must be carved into a base mesh.

Three escape paths (out of pure-recipe scope but reachable via Blender MCP)

1. Import an existing human base mesh — via:

   • mcp__blender__download_polyhaven_asset (CC0 character assets)
   • mcp__blender__download_sketchfab_model (CC-BY models)
   • mcp__blender__generate_hyper3d_model_via_text (text-to-3D AI generation)

   Then chain the orchestrator pipeline: subsurface skin material, character lighting, hero camera, render.

2. Sculpt mode — gestural; recipe prepares a base mesh, user sculpts manually

3. Commission a Blender character artist per prompts/04-blender-workflow.md (6-10 hours)

What this contributes methodologically

Three honest scope boundaries are now codified across the plugin:

Version	Hard limit	Beyond
v0.8.0	Aesthetic design quality	Style libraries
v1.2.0	Character production quality	Sculpting / artist commission
v1.2.1	Human face from primitives	AI 3D / mesh import / sculpt / artist

Each limit comes with a concrete escape path. The skill plugin doesn't fight character work anymore — it redirects honestly to the right tool.

Validation proof

04_broadcaster_with_features_still_not_human.png — even with nose/ears/mouth/brows added, primitives don't carve a human face.

v1.2.0 — Broadcaster avatar test; character-scope boundary

Stress-tested the skill against docs/avatar-design-kit/prompts/01-concept-sheet.md — a Max-Headroom-flavour digital broadcaster character.

Built a stylized primitives-only version using existing recipes; documented what works and what doesn't.

What works

Sphere-head broadcaster silhouette with subsurface skin + sheen suit + flat hair + aviator glasses + dramatic cyan/magenta lighting. Final synthwave-lit render shows recognizable retro-CGI broadcaster look.

The subsurface skin recipe (Subsurface Weight 1.0, Radius (1.0, 0.25, 0.10)) validates the v0.5.0 set_input helper for the disabled Subsurface IOR input on Blender 5.x.

What doesn't (honest scope boundary)

• Realistic facial features (eyes, nose, mouth, ears) — primitives can't carve these
• 15-viseme animation blendshapes per TECH-SPEC.md
• Hand-textured skin / believable hair / proper anatomy
• Posing / rigging / production character animation

The orchestrator now warns users that automated generation produces a recognizable silhouette only for character work.

New recipe finding

Strong colored lighting (cyan/magenta synthwave) overpowers subtle PBR materials. First attempt with 800W cyan + 600W magenta washed everything out. Final at 250W cyan + 200W magenta + 15W warm fill + world Strength 0.15 produced a credible synthwave broadcaster.

Validation proof

Three render iterations committed: 01_broadcaster_too_bright.png, 02_broadcaster_neutral_dominates.png, 03_broadcaster_synthwave_FINAL.png — honest journey from broken to acceptable.

v1.1.0 — Desk lamp + emission material + practical lighting

Fourth scene class validated end-to-end: desk lamp with articulated arms + shade + emissive bulb. Tests two genuinely new things:

1. Emission material — the missing primary material class. Replaces Principled BSDF with ShaderNodeEmission for light-emitting meshes (bulbs, neon, screens).
2. Practical lighting — when subject contains its own light source. Dim world + drop 3-point fill/rim + subtle ambient fill from camera + high emission strength + Cycles bounces ≥ 16.

New recipes

File	Recipe
blender-materials/SKILL.md	Recipe 11b — Emission (with strength-tuning table for 5 mesh sizes; sub-recipe for shade interior with flipped normals)
blender-lighting/SKILL.md	Recipe 0c — Practical lighting (5-step setup)

Key insight

Mesh emission strength scales with surface area (not light-object intuition). A 1.8cm bulb sphere needs Strength=1500 to read like a real bulb; Strength=50 is invisible. Strength-tuning table covers 5 mesh sizes from Edison-bulb to window-plane.

Validation proof

desk_lamp_emission.png — recognizable articulated desk lamp with visible bulb glow inside the shade, warm pool of practical light cast on the desk, lamp body silhouetted against dark scene.

v1.0.0 — First stable release

First stable release of cc-blender-skill — a Claude Code skill plugin that drives Blender 5.x via natural language.

Highlights

• 10 chain-loadable skills: orchestrator + 8 domain skills + wireframe-to-3d specialty
• Validated on Blender 5.1.1 end-to-end across three scene classes (sword, bottle, chair)
• Wireframe-to-3d closure: aviator wireframe → 21 contours → recognizable Ray-Ban-style render
• 200-query trigger-eval set across the 10 skills
• Cross-version compat documented for Blender 4.x and 5.x users
• Honest scope boundaries: design quality ≠ build correctness, wireframe-to-3d as foundation not deliverable

What's stable

Pipeline: world reset → real-world dimension lookup → modeling → materials → lighting → camera → render → export → visual-validation checkpoint.

All Blender 5.x cross-version patches verified live (BLENDER_EEVEE_NEXT fallback, action.fcurves compat helper, set_input for disabled BSDF inputs, ensure_camera guard).

Subject-class lighting (metal / glass / wood / fabric / skin / product), volume absorption recipe for coloured glass, connection-overlap pattern, real-world dimension reference for swords / chairs / bottles / mugs / tables / lamps / eyewear.

Install

git clone git@github.com:RobLe3/cc-blender-skill.git
cd cc-blender-skill
for skill in plugin/skills/*/; do
    name=$(basename "$skill")
    ln -sfn "$(pwd)/$skill" "$HOME/.claude/skills/$name"
done

Prerequisites: Blender ≥ 4.0 with the BlenderMCP addon running on port 9876; pip install opencv-python numpy scipy Pillow for wireframe-to-3d.

What v1.0.0 doesn't include (honestly)

• Aesthetic-design quality (curved chair backs etc.) — out of automatic scope
• Reliable wireframe-to-3d for complex named-design objects
• Suppressed thin-metal specular flare in side lighting
• External-user feedback loop — internal validation only
• Cross-tested Blender 4.x install

See CHANGELOG.md for the full version history.