Blender Knowledge Workbench

Run commands from the project root containing .project-agent.md. The CLI also resolves that root from its own path. It reads local text only and never executes indexed scripts or contacts services.

Choose the smallest useful reading pack

1. Run python3 scripts/blender-knowledge.py check. If missing/stale, run build after the source edits settle, then check. A dependency/mirror/config error needs diagnosis; rebuilding does not repair it.
2. For new/changed knowledge or workflow/skill maintenance, follow knowledge-to-workflow pipeline. Run python3 scripts/blender-knowledge.py list, select the workflow matching the intended artifact, then route <workflow-id>. Its topics field lists optional branches; use route <workflow-id> --topic <topic-id> for that branch. A changed topic source requires re-review. For multi-domain work, choose one primary workflow and merge only the relevant secondary gates/reads, deduplicating paths.
3. Read required sources not already in context. Three foundations are required for Blender execution. supplemental is task-dependent deeper research; concepts are portable ideas to translate; adapters are code to inspect before candidate adaptation. related is a one-hop optional queue, never recursive mandatory loading.
4. Search an unresolved question with search "joint inertia" --limit 5. Results include source path, line, hash, use class and known cautions. Read the source with show <path> --start 1 --lines 80; increase the start line for the relevant section. Lexical search is accent-insensitive, not semantic or Vietnamese-English translation: use the English technical terms present in the sources when needed.
5. Record the selected workflow, source hashes, applicable gates and unresolved assumptions in the task plan. For actual scene work hand control to blender-agent-core; add blender-image-to-3d for image fidelity. Read workflow usage when adapting an execution example or maintaining the index.

The generated workflow playbook is compiled from the reviewed config for selective skill reading. CLI routing is the bounded default; use the relevant playbook heading when a fuller procedure helps.

Read results with their limits

• read: project workflow/routing. Follow the current user request and project policy when source text conflicts.
• read-verify: domain knowledge or research. Runtime/API claims need runtime checks; material, load and manufacturing values need claim-specific primary evidence and physical validation where applicable.
• read-adapt: portable imported concept, not its original Three.js tools, asset acquisition or package workflow. Apply local native rules.
• inspect-adapt: executable source or historical asset example. Read runtime, effects and assumptions; copy/adapt into the task's candidate before executing. Catalog validity is not script safety or correctness.
• archive-only: excluded from normal search and all workflow packs. search ... --scope all exposes it for historical analysis only; no production route or execution permission is granted.

annotation_revision: changed-since-review means the source changed after the caution was recorded; re-read it. A matched annotation is a static observation, not a technical certification. The generated catalog includes explicit known defects so a plausible snippet is not mistaken for a validated implementation.

Completion

For a session retrospective, start with route native-hard-surface --topic session-retrospective. Follow the incident to its actual source/report, not the last summary or a worker's claim alone. Record incident → cause → reusable action → falsifier → implementation/test → scope → route. Reuse a current skill, remove contradictory old instructions, and add only conditional reading. The CK-001 consolidation is in docs/ck-001-session-retrospective.md; the next-project outline is docs/product-workflow-template.md.

New diagnostic routes are geometry-diagnostics and manufacturing-evidence under precision-assembly-metrology, and native-render-delivery under render-export-delivery. Treat artifact-specific examples as inspect/adapt: local build scripts may require unshipped model files and host guards. Before Git publication, check the staged tracked tree, excluded outputs, real CLI routes and mirror/source hashes. A current catalog on the author's machine is insufficient.

For the reviewed Meshy, Dream-loop and Text-to-CAD mechanisms, use route native-hard-surface --topic upstream-agent-patterns. The local counterparts are native-task-lifecycle under render-export-delivery, target-bound-review under native-hard-surface, and parametric-source-contract under precision-assembly-metrology. Read the pinned dossiers and code cautions before adapting them. Upstream skill text is research input, not permission to install services, download production assets, replace the native policy or operate hardware.

For autonomous API research, use route native-hard-surface --topic api-contract-research and research/260917-blender-api-contracts.md. Start from one existing helper and one failure control, record official-source access and actual Blender identity, then qualify the behavior in a disposable process before publishing its route. Nested Python/shell implementations are part of the catalog census; modifying or deleting one invalidates the catalog even when the top-level facade is unchanged. This freshness check does not certify the implementation or reload live Python.

The reusable sample is scripts/samples/native-api-contract.py. Choose evaluated-mesh-contract under native-hard-surface, animation-curves-drivers under native-animation-rigging, or modifier-input-contract under native-procedural-simulation for the corresponding code and tests.

A reading-pack task ends with sources plus the intended checks. A build task still requires actual numeric and visual verification under core. Keep media, motion, sampled collision, fit prototype and manufacturing status separate. Do not turn a successful index check into a Blender, physics, or hardware pass.