Add direct Blender attachment alignment tool

[Ker102]

Summary

• add align_object_attachment_points to the ViperMesh Blender addon and public download copy
• wire the tool through LangChain, the orchestration registry/filter, system prompt, and spatial positioning guide
• update capability inventory and add focused coverage for attachment-point routing

Validation

• npx tsx scripts/test/test-blender-attachment-alignment-tool.ts
• npx tsx scripts/test/test-tool-guide-trigger-coverage.ts
• npx tsx scripts/test/test-blender-capability-inventory.ts
• python -m py_compile desktop/assets/vipermesh-addon.py public/downloads/vipermesh-addon.py
• npx tsc --noEmit --incremental false
• npm run lint
• git diff --check

Note: lint still reports the existing baseline-browser-mapping freshness warning.

Summary by CodeRabbit

• New Features
  • Added new attachment point alignment capability: precisely position objects by connecting their local attachment/joint points, with optional world-space offsets and rotation preservation for complex assemblies and rotated parts.

[coderabbitai]

Note

Reviews paused

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

Warning

Review limit reached

@Ker102, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 48 minutes and 7 seconds. Learn how PR review limits work.

Your organization has run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: e7fcb01f-b01d-4ed9-9199-c5c3e2648982

📥 Commits

Reviewing files that changed from the base of the PR and between 79b76bc and 425bceb.

📒 Files selected for processing (2)

• lib/ai/agents.ts
• scripts/test/test-blender-attachment-alignment-tool.ts

📝 Walkthrough

Walkthrough

This PR adds align_object_attachment_points, a new Blender MCP tool that translates an object so its local attachment point aligns with a reference object's local point, with optional offset. The implementation includes the Blender addon method, TypeScript agent wiring, orchestration metadata, system prompt guidance, tool guide documentation, and comprehensive static tests covering all layers.

Changes

Attachment Point Alignment Tool

Layer / File(s)	Summary
Blender addon alignment implementation desktop/assets/vipermesh-addon.py, public/downloads/vipermesh-addon.py	Adds align_object_attachment_points() method with input validation, world-space matrix math to compute local-to-world point conversion, translation delta calculation, and structured result/error responses; both copies include command dispatch routing.
Agent tool definition and registration lib/ai/agents.ts	Defines tool with Zod schema for object names, local 3D point arrays, optional offset, and rotation preservation flag; registers in ALL_TOOLS and forwards to executeMcpCommand(...).
Tool registry, filtering, and keyword routing lib/orchestration/tool-registry.ts, lib/orchestration/tool-filter.ts	Registers tool metadata in TOOL_REGISTRY, adds to geometry category, expands keyword detection with attachment, attachment point, local point, connect point, joint, and hinge, and updates category map routing.
System prompt and tool guidance updates lib/orchestration/prompts/blender-agent-system.md	Adds tool to Transform & Scene Management Tools list with signature and extends "When to Use Which Tool" table to map attachment-by-local-connection-points tasks to the new tool.
Tool guide and capability inventory data/tool-guides/spatial-positioning-guide.md, docs/blender-mcp-capability-inventory.md	Adds "Direct Tool Attachment Point Alignment" section with example showing local points and world-space delta alignment; updates frontmatter trigger binding and increments command count from 85 to 86.
Comprehensive static testing and validation scripts/test/test-blender-attachment-alignment-tool.ts, scripts/test/test-tool-guide-trigger-coverage.ts	Validates Python implementation patterns (matrix conversions, translation, rotation handling), verifies orchestration wiring (tool filtering, prompt mentions), checks agent/system-prompt/guide cross-references, and enforces trigger coverage binding.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• Ker102/ViperMesh#54: Both PRs extend the same Blender MCP tool wiring infrastructure (command routing, agent tool exposure, tool-filter categories, orchestration metadata) but for different new commands.

Suggested labels

documentation, backend, desktop, scripts

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 61.54% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and specifically describes the main change: adding a direct Blender attachment alignment tool called align_object_attachment_points across the codebase.
Description check	✅ Passed	The PR description is well-structured with a clear summary of changes, validation steps, and testing commands, though it doesn't follow the template format with explicit sections like Type of Change, Related Issues, or the checklist items.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feature/blender-attachment-alignment-tools

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@lib/ai/agents.ts`:
- Line 635: The preserve_rotation schema currently uses z.boolean().optional()
but the description claims only true/default is supported; to fix, either remove
the preserve_rotation field entirely from the schema and related usage until
rotation alteration is implemented, or restrict it to accept only true by
replacing z.boolean().optional() with a schema that only allows true (e.g.,
z.literal(true).optional() or z.true().optional()) and update the describe text
to state that only true is accepted and that passing false will be rejected;
locate the preserve_rotation entry in the agent input schema in lib/ai/agents.ts
and apply one of these two changes and adjust any callers/validation messages
accordingly.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: 49a2717e-a960-4980-bb42-f9f2accddfee

📥 Commits

Reviewing files that changed from the base of the PR and between d1cc99e and 79b76bc.

📒 Files selected for processing (10)

• data/tool-guides/spatial-positioning-guide.md
• desktop/assets/vipermesh-addon.py
• docs/blender-mcp-capability-inventory.md
• lib/ai/agents.ts
• lib/orchestration/prompts/blender-agent-system.md
• lib/orchestration/tool-filter.ts
• lib/orchestration/tool-registry.ts
• public/downloads/vipermesh-addon.py
• scripts/test/test-blender-attachment-alignment-tool.ts
• scripts/test/test-tool-guide-trigger-coverage.ts

[Ker102]

@coderabbitai ignore

Applied the single actionable review item by restricting preserve_rotation to true/default at the agent schema boundary and validated the targeted test plus TypeScript compile. Skipping a second automated review run per project workflow.

[coderabbitai]

@Ker102 Understood — pausing automated reviews for this PR. Thanks for confirming the preserve_rotation constraint fix and the validation steps.

✅ Actions performed

Reviews paused.