Start Geometry Nodes translation corpus

docs/research/geonodes-translation-corpus.md

@@ -0,0 +1,118 @@
+# Geometry Nodes Translation Corpus
+
+This note tracks public Geometry Nodes examples that are useful for learning how
+to translate visual node graphs into Geometry Script. The goal is not to collect
+cool files. The goal is to build a graded ladder from known node networks to
+scripts we can generate, inspect, render, and revise.
+
+## Source Selection Rules
+
+- Prefer `.blend` files or repositories with real node groups over screenshot
+  and video-only tutorials.
+- Prefer examples with clear visual outcomes and bounded mechanisms.
+- Use Blender itself to inspect node groups before recreating anything.
+- Translate one graph idiom at a time into Geometry Script.
+- Verify each translation by generating a node group in Blender, inspecting its
+  node/link shape, and rendering when the visual result matters.
+- Keep video-only sources as secondary explanation, not primary truth.
+
+## Complexity Ladder
+
+### Tier 1: Primitive Construction And Simple Fields
+
+Use these to learn Geometry Script signatures, result objects, chain syntax,
+modifier sockets, and basic graph inspection.
+
+- `Shriinivas/geometrynodes`
+  - Source: https://github.com/Shriinivas/geometrynodes
+  - Candidate files: `cartesian.blend`, `paramnpolareq.blend`,
+    `piechart.blend`, `fieldvalue.blend`
+  - Why it matters: small mathematical graphs with clear output shapes.
+  - Translation value: curve generation, mesh primitives, math nodes, exposed
+    parameters, and field/value flow.
+
+### Tier 2: Scattering, Instancing, And Attribute Flow
+
+Use these after the primitive layer can be recreated without guessing.
+
+- Blender Guru beginner Geometry Nodes candy tutorial
+  - Source: https://www.blenderguru.com/tutorials/2025/9/10/blender-tutorial-geometry-nodes-for-beginners
+  - Candidate artifact: downloadable final `.blend`
+  - Why it matters: canonical beginner scatter workflow.
+  - Translation value: distribute points, instance on points, random rotation,
+    random scale, join geometry, and exposed controls.
+
+- Samuel Sullins demo file via BlenderNation
+  - Source: https://www.blendernation.com/2023/04/20/learn-geometry-nodes-with-this-demo-file/
+  - Candidate artifact: free demo `.blend` with node comments and simple
+    scattering setups.
+  - Why it matters: likely built for learning and rebuilding.
+  - Translation value: comments may make node intent easier to map into prose
+    and Geometry Script.
+
+### Tier 3: Reusable Utility Node Groups
+
+Use these to learn how artists package node networks into inspectable tools.
+
+- `quellenform/blender-CurveToMeshUV`
+  - Source: https://github.com/quellenform/blender-CurveToMeshUV
+  - Candidate file: `Curve to Mesh UV v1.7.02.230213-FREE - Blender 3.4+.blend`
+  - Why it matters: a focused utility group with a clear contract.
+  - Translation value: curve-to-mesh workflows, UV attributes, face-corner
+    domain discipline, output attribute handling.
+
+- `Tams3d/T3D-GN-Presets`
+  - Source: https://github.com/Tams3d/T3D-GN-Presets
+  - Candidate file: `t3d_nodes.blend`
+  - Why it matters: a large preset library for Blender 4.4+ with many utility
+    node groups.
+  - Translation value: reusable group organization, socket naming, matrix and
+    deformation utilities. This is not a first target; it is a quarry.
+
+### Tier 4: Procedural Systems
+
+Use these only after the smaller idioms are reliable.
+
+- Blender Studio Geometry Nodes from Scratch files
+  - Source: https://studio.blender.org/training/geometry-nodes-from-scratch/chapter/files/
+  - Candidate files: rock scattering, tree generator, grass tuft generator,
+    spaceship generator, geometry components demo.
+  - Why it matters: production-adjacent learning files with a broad concept
+    range.
+  - Translation value: progressive systems that combine distribution,
+    attributes, generated geometry, materials, and exposed controls.
+
+- `IRCSS/Trees-With-Geometry-Nodes-Blender`
+  - Source: https://github.com/IRCSS/Trees-With-Geometry-Nodes-Blender
+  - Candidate artifact: tree-generation node groups.
+  - Why it matters: procedural tree generation based on curves and instancing.
+  - Translation value: recursive-looking branch systems, curve distortion,
+    instance orientation, scale variation, and material variation.
+
+## First Translation Target
+
+Start with `Shriinivas/geometrynodes` because it is public, GitHub-hosted, MIT
+licensed, and contains several bounded `.blend` examples. The first useful
+translation is a tiny graph from `cartesian.blend` or `piechart.blend`, chosen
+after node group inspection.
+
+## Extraction Workflow
+
+1. Download one source `.blend` into an ignored experiment folder.
+2. Run Blender headlessly to list geometry node groups, group interface sockets,
+   node types, link counts, and exposed modifiers.
+3. Pick one small node group and write a plain-language graph map:
+   inputs, generated geometry, fields/attributes, materials, outputs, and why
+   each stage belongs.
+4. Recreate that group with Geometry Script using local generated 5.1 docs for
+   signatures.
+5. Smoke-test generation in Blender and compare node types/link shape against
+   the source.
+6. Render only after the graph structure is close enough to make visual review
+   meaningful.
+
+## Known Tooling Need
+
+We need a small Blender inspection script that can summarize node groups from a
+`.blend` file into JSON. Without that, every example becomes manual archaeology
+with better branding.

notes/fresh-workspace-handoff.md

@@ -23,11 +23,12 @@ git log --oneline -5
 ## Current State
 
 VibeGeometry is an initial scaffold. It has persistence machinery, project
-orientation docs, and helper tools, but no Blender builder library or artifact
-schemas yet.
+orientation docs, helper tools, and an initial Geometry Nodes translation corpus
+note, but no Blender builder library or artifact schemas yet.
 
-The current next action is to draft the scene brief and node graph manifest
-schemas, then validate them against one tiny reference-driven example.
+The current next action is to build the first Geometry Nodes translation corpus
+entry by inspecting a small public `.blend` node group, mapping its graph in
+prose, and recreating it with Geometry Script.
 
 ## Important Invariants
 
@@ -47,6 +48,8 @@ schemas, then validate them against one tiny reference-driven example.
 - What exact JSON shape should the scene brief use for references,
   instructions, target traits, and acceptance criteria?
 - What should the first node graph manifest schema require versus merely allow?
+- What node-group inspection JSON shape is most useful for translating public
+  `.blend` examples into Geometry Script?
 - Which Blender 5.0+ APIs and node construction helpers should become the
   first stable builder layer?
 - What is the smallest useful render-review artifact?

notes/vibegeometry-implementation-plan.md

@@ -13,37 +13,46 @@ should not carry live next-action clutter.
 
 ## Near-Term Sequence
 
-1. Define the scene brief contract.
+1. Build the first Geometry Nodes translation corpus entry.
+   - Start from a small public `.blend` with inspectable node groups.
+   - Use Blender to summarize group sockets, node types, links, modifiers, and
+     graph shape before translating.
+   - Write a plain-language map of one source graph before scripting.
+   - Recreate the graph with Geometry Script using the local Blender 5.1
+     generated Geometry Script docs for signatures.
+   - Smoke-test the generated node group in Blender before rendering.
+
+2. Define the scene brief contract.
    - Capture references, text instructions, target visual traits, constraints,
      camera/composition requirements, acceptance criteria, and known unknowns.
    - Preserve source paths or URLs for every reference image.
    - Separate visual target description from implementation strategy.
 
-2. Define the node graph manifest contract.
+3. Define the node graph manifest contract.
    - Describe node groups, sockets, exposed controls, modifiers, attribute
      names, field flow, materials, and dependencies.
    - Require enough naming and rationale for future agents to inspect the graph.
    - Keep graph contracts Blender 5.0+ oriented.
 
-3. Build a minimal Python builder seam.
+4. Build a minimal Python builder seam.
    - Start with one tiny scene that proves graph construction, material setup,
      camera, lighting, save, and render orchestration.
    - Prefer small composable helpers for node group creation and socket linking.
    - Avoid a giant builder abstraction until repeated graph idioms demand it.
 
-4. Build render review artifacts.
+5. Build render review artifacts.
    - Store render path, scene brief id, manifest id, script path, Blender
      version, review status, visual misses, graph issues, and next hypothesis.
    - Treat rendered output as the acceptance surface for visual claims.
 
-5. Add geometry-node idiom notes and examples.
+6. Add geometry-node idiom notes and examples.
    - Document established patterns for distribution, instancing, curve/surface
      generation, attributes, material variation, simulation zones, and exposed
      parameters.
    - Keep examples small enough to inspect.
    - Promote only graph patterns that survive review.
 
-6. Generalize after the loop works.
+7. Generalize after the loop works.
    - Add reference-image ingestion helpers.
    - Add headless batch rendering.
    - Add visual comparison or reviewer prompts.

state/evidence.jsonl

@@ -1,3 +1,4 @@
 {"ts":"2026-05-04T00:00:00+00:00","type":"scaffold","status":"accepted","note":"Initialized VibeGeometry with Epiphany-style persistence surfaces adapted to Blender 5.0+ geometry-node scene generation."}
 {"ts": "2026-05-04T11:52:15+00:00", "type": "research", "status": "ok", "note": "Geometry Script add-on is installed under Blender 5.1 and imports headlessly. A trivial cube node group built successfully in Blender 5.1.1; the documented grid().mesh_to_points() chain failed with NoneType callable, so Geometry Script should be treated as promising but each idiom must be smoke-tested against the installed Blender/add-on pair."}
 {"ts": "2026-05-04T11:55:00+00:00", "type": "research", "status": "ok", "note": "Local Geometry Script 5.1 generated docs are the authoritative node-signature source for this workspace. The prior grid().mesh_to_points() probe failed because grid() returns a result object with mesh and uv_map; the valid chain is grid(...).mesh.mesh_to_points(...)."}
+{"ts": "2026-05-04T12:11:47+00:00", "type": "research", "status": "accepted", "note": "Public Geometry Nodes learning material is mostly screenshots, videos, and downloadable .blend files. VibeGeometry should build durable Geometry Script knowledge by inspecting source .blend node groups, mapping one graph at a time in prose, then recreating and smoke-testing with local Geometry Script 5.1 signatures."}

state/map.yaml

@@ -77,4 +77,4 @@ data_flow:
 
 current_status:
   summary: VibeGeometry has an initial Epiphany-style persistence scaffold adapted for Blender geometry-node scene generation, with project-neutral state, handoff, architecture notes, and helper tools.
-  next_action: Draft the scene brief and node graph manifest schemas, then validate them against one tiny reference-driven example.
+  next_action: Build the first Geometry Nodes translation corpus entry by inspecting a small public `.blend` node group, mapping its graph in prose, and recreating it with Geometry Script.