feat: author resource-aware riverbank grove

docs/ARCHITECTURE_OVERVIEW.md

@@ -69,6 +69,10 @@ interaction positions by action and horizontal cell, plus authoritative
 metadata bounds copied at bind time. It does not own amounts, enabled state,
 reservations, or persistence. `ResourceNode` enter/exit, bind, and transform
 notifications keep it synchronized with the loaded presentation lifecycle.
+Resource anchors may be nested inside authored presentation clusters: runtime
+discovery uses their stable IDs and registration lifecycle, never a parent
+path. Decorative siblings without a `ResourceNode` remain outside the index
+and simulation state.
 
 Outside the runtime lifecycle, `simulation/benchmark/` owns reusable,
 schema-valid workload fixtures. CLI tools and headless scenarios consume those

docs/BUILD_IN_PUBLIC_PLAN.md

@@ -780,16 +780,22 @@ Completed:
     aligned; softened foam/mist and a smaller rock frame make the falls part of
     the landform. A matched Metal capture records the change, and the rebaked
     navigation mesh passes terrain-height and runtime route checks.
+37. `Jajce Resource Grove 04`: the right riverbank now groups 28 intentionally
+    instanced fern/flower/stone details and two decorative trees around two
+    existing finite resources. The berry and tree keep their stable IDs and
+    metadata, use specific visuals instead of boxes, and remain reachable from
+    separate terrain-snapped approach points. Matched captures and a focused
+    scenario prove three-batch visual cost, nested discovery, and a forced
+    query beyond the first 24 m range without changing the 18-resource state.
 
 Next:
 
-1. Prove one bounded foliage/resource authoring workflow at a riverbank or
-   forest edge. Use decorative Terrain3D/intentional instances for tree, fern,
-   flower, and rock masses, but create simulation-owned finite resources only
-   through selected stable-ID `ResourceNode` anchors.
-2. Validate that villagers discover both nearby and farther authored anchors,
-   preserve reachable interaction points, and keep the visual batch inside a
-   measured presentation budget. Add livestock only with a real identity and
+1. Give the authored berry/tree resources state-driven low/depleted visuals
+   sourced from their real `ResourceStateRecord` amount. Prove NPC and player
+   extraction plus save/restore rebuild the same presentation without adding
+   visual fields to simulation state.
+2. Apply the workflow to a second forest-edge consumer only after that contract
+   is honest and reusable. Add livestock only with a real identity and
    interaction contract.
 
 Do not start with GIS data, a full city, a large asset pack, or more NPC

docs/LEARNING_ROADMAP.md

@@ -896,17 +896,30 @@ plunge basin, and curved downstream channel. A matched Metal capture records
 the result, and the Terrain3D-derived navigation mesh was rebaked and validated
 against required village/resource routes.
 
-The immediate next slice should prove one bounded foliage/resource authoring
-workflow in the real world: build a restrained riverbank or forest-edge cluster
-with decorative Terrain3D/intentional instances, pair only selected harvestable
-trees or berry patches with stable-ID `ResourceNode` anchors, and verify nearby
-and farther loaded anchors remain discoverable through `ActiveWorldAdapter`.
-Keep decorative instances out of simulation state, measure the bounded visual
-cost, and do not generalize the resource grid to people/buildings/events or
+The first authored foliage/resource workflow is complete. One riverbank cluster
+uses three intentional MultiMesh batches for 28 fern, flower, and stone
+instances plus two decorative trees, while only an existing stable-ID berry and
+tree are finite `ResourceNode` anchors. Both anchors preserve the save contract
+of eighteen resources, sit above the carved channel, and expose separate
+terrain-snapped approach points. A forced village query expands beyond the
+initial 24 m range and selects the nested berry exactly by ID.
+
+The immediate next slice should make those two resource-specific visuals
+reflect authoritative amount/depletion: thin the berry patch and leave a stump
+or equivalent readable tree state after real NPC/player extraction, then prove
+save/restore rebuilds the same presentation without persisting visual-only
+state. Only after both the berry and tree consume that contract should shared
+cluster/depletion tooling be extracted or the workflow copied to a forest
+edge. Do not generalize the resource grid to people/buildings/events or
 introduce active/abstract LOD before those consumers need it.
 
 Recently completed:
 
+- `Jajce Resource Grove 04`: two existing river resources now live as nested
+  stable-ID anchors inside a restrained decorative bank cluster. Twenty-eight
+  understory instances use three MultiMesh batches, bespoke berry/tree visuals
+  replace generic boxes, terrain-snapped approach points remain reachable, and
+  a real far-source query proves parent-path-independent expanding discovery.
 - `Jajce River 03`: deterministic Terrain3D generation now carves the upper
   stream, raised waterfall shelf, plunge basin, and curved downstream channel;
   shared watercourse geometry keeps both water ribbons aligned, soft masked

docs/PROJECT_CONTEXT.md

@@ -354,7 +354,9 @@ but retain far sources whenever their authoritative metadata can still win.
   transforms, authored conifer clusters, and oversized ambient butterflies;
 - one sparse terrain-aware calligraphic gust field with two or three soft
   tapered strokes per burst;
-- eighteen ResourceNodes preserving stable food/wood discovery IDs;
+- eighteen ResourceNodes preserving stable food/wood discovery IDs, including
+  one riverbank cluster that nests two finite anchors among 28 decorative
+  fern/flower/stone instances in three bounded MultiMesh batches;
 - typed village pantry storage and typed guard, study, and rest activity sites;
 - a Terrain3D-derived baked navigation mesh covering the current playable loop;
 - base collision/navigation guardrails that keep Terrain3D collision enabled,
@@ -980,13 +982,14 @@ Raw samples and workload exclusions live in
 [Simulation scaling baseline 02](benchmarks/SIMULATION_SCALING_BASELINE_02.md)
 and [Loaded Resource Discovery 01](benchmarks/LOADED_RESOURCE_DISCOVERY_01.md).
 
-The authored Jajce watercourse and its Terrain3D-derived navigation rebake are
-complete. The next slice should prove a bounded stable-ID resource-anchor
-placement workflow beside decorative Terrain3D/intentional foliage instances
-at one riverbank or forest edge. It should validate nearby and farther loaded
-resource discovery, reachable interaction points, and a measured presentation
-budget without making decorative instances authoritative. Do not yet
-generalize the resource grid or introduce active/abstract simulation LOD.
+The authored Jajce watercourse, navigation rebake, and first bounded
+foliage/resource placement proof are complete. The next slice should derive
+low/depleted berry and tree visuals from authoritative resource amount, cover
+real NPC/player extraction and save/restore reconstruction, and keep that
+presentation out of serialized simulation state. Apply the cluster workflow to
+a second forest edge only after the depletion contract supplies a real second
+consumer. Do not yet generalize the resource grid or introduce active/abstract
+simulation LOD.
 
 The remaining simulation-garden target still aims for:
 

docs/RESOURCE_NODE_MIGRATION.md

@@ -567,6 +567,16 @@ existing `ResourceStateRecord`. The reviewed 18/180/1,800-source benchmark and
 exact-selection contract live in
 [Loaded Resource Discovery 01](benchmarks/LOADED_RESOURCE_DISCOVERY_01.md).
 
+The first authored placement proof now nests `berry_bush_river_02` and
+`tree_river_resource_01` inside one riverbank cluster without changing their
+IDs, metadata, or the eighteen-resource save contract. Twenty-eight decorative
+understory instances and two silhouette trees remain presentation-only. The
+finite anchors have resource-specific visuals and separate terrain-snapped
+approach points; recursive navigation checks cover both, while a forced query
+selects the farther berry only after expanding beyond the first 24 m range.
+The matched review lives in
+[Jajce Resource Grove 04](baselines/JAJCE_RESOURCE_GROVE_04.md).
+
 ## Test scenarios
 
 At minimum, exercise:

docs/baselines/JAJCE_RESOURCE_GROVE_04.md

@@ -0,0 +1,76 @@
+# Jajce Resource Grove 04
+
+Captured: 2026-07-17
+
+## Files
+
+- [before overview](jajce_resource_grove_04_before.png)
+- [after overview](jajce_resource_grove_04_after.png)
+- `world/jajce/RiverbankResourceCluster.tscn`
+- `tests/jajce_resource_cluster_test.gd`
+
+The images use the same 1280×720 camera, fixed daylight value, warmup, and
+Metal renderer. The new cluster is on the right bank beside and beyond the
+bridge; the comparison intentionally keeps the broader citadel/waterfall
+composition unchanged.
+
+## Visual reduction
+
+The former river edge had one isolated deciduous tree and conifer, while two
+generic-box resource anchors sat separately from the foliage language. The
+after frame gathers that silhouette into one restrained bank mass:
+
+- 12 low-poly fern clumps;
+- 9 oversized warm flower heads;
+- 7 flattened bank stones;
+- 2 decorative silhouette trees; and
+- 2 finite anchors with distinct berry-patch and harvestable-tree visuals.
+
+The 28 understory details use three `MultiMeshInstance3D` batches. The berry
+visual adds five wind-reactive leaf clumps and eight deliberately readable
+berries. This is a bounded authored accent, not a world-wide scatter pass.
+
+## Authority and authoring contract
+
+`DecorativeInstances` contains no `ResourceNode` descendants. Its trees,
+ferns, flowers, and stones are transient presentation and never enter saves,
+checksums, reservations, or resource conservation.
+
+`ResourceAnchors` contains only `berry_bush_river_02` and
+`tree_river_resource_01`. These are the same existing IDs and definitions, now
+nested inside the authored cluster. `ResourceNode` registration and
+`ActiveWorldAdapter` discovery do not depend on a parent path, so simulation
+authority still binds exactly 18 resources.
+
+The visible plants sit on the raised Terrain3D bank. Each anchor has a separate
+approach marker snapped to the lower bank surface, keeping the visual context
+honest without asking NPCs to climb an unreachable slope. All required
+navigation routes reach those markers and remain close to Terrain3D height.
+
+## Far-discovery proof
+
+The berry interaction point is approximately 30.5 m from the village origin,
+beyond the adapter's initial 24 m query radius. The focused scenario first
+confirms ordinary nearby food remains available, then disables every other food
+source in authoritative state. `ActionTargetResolver` expands through more than
+one range pass and selects `berry_bush_river_02` by stable ID. The test also
+checks that direct and nested anchors produce the same 18-entry index.
+
+## Remaining work
+
+The resource-specific visuals currently identify finite sources but do not yet
+thin or change shape as their authoritative amount falls. The next vertical
+slice should show low/depleted berries and a stump or equivalent tree state
+after real NPC/player extraction, then verify save/load reconstructs the same
+visual from `ResourceStateRecord` without serializing presentation fields.
+
+## Capture command
+
+```bash
+HOME="$PWD/logs/quality/godot_profile" \
+APPDATA="$PWD/logs/quality/godot_profile" \
+LOCALAPPDATA="$PWD/logs/quality/godot_profile" \
+/Applications/Godot.app/Contents/MacOS/Godot \
+  --path "$PWD" --script res://tools/capture_jajce_lookdev.gd -- \
+  --output=res://docs/baselines/jajce_resource_grove_04_after.png
+```

docs/baselines/JAJCE_RIVER_03.md

@@ -60,11 +60,11 @@ player resource gathering with all 18 finite resource anchors loaded.
 
 ## Next visual/system proof
 
-The next pass should author one bounded riverbank or forest-edge foliage mass,
-using decorative Terrain3D/intentional instances for visual density and only a
-small selected set of stable-ID `ResourceNode` anchors for finite harvestable
-resources. Bank stones, ferns, flowers, and tree masses can improve the channel
-edge during that proof. Bridge, buildings, and fortress geometry remain
+That proof is complete in
+[Jajce Resource Grove 04](JAJCE_RESOURCE_GROVE_04.md): a bounded riverbank mass
+keeps decorative density separate from two stable-ID finite anchors. The next
+pass should make those berry/tree visuals reflect real depletion before adding
+a second forest-edge cluster. Bridge, buildings, and fortress geometry remain
 prototype blockouts and should be replaced gradually rather than through a
 broad asset dump.
 

docs/baselines/jajce_resource_grove_04_after.png.import

@@ -0,0 +1,40 @@
+[remap]
+
+importer="texture"
+type="CompressedTexture2D"
+uid="uid://drip3uanxmac0"
+path="res://.godot/imported/jajce_resource_grove_04_after.png-400fd71bda2bd7202805c1ba66aa8c28.ctex"
+metadata={
+"vram_texture": false
+}
+
+[deps]
+
+source_file="res://docs/baselines/jajce_resource_grove_04_after.png"
+dest_files=["res://.godot/imported/jajce_resource_grove_04_after.png-400fd71bda2bd7202805c1ba66aa8c28.ctex"]
+
+[params]
+
+compress/mode=0
+compress/high_quality=false
+compress/lossy_quality=0.7
+compress/uastc_level=0
+compress/rdo_quality_loss=0.0
+compress/hdr_compression=1
+compress/normal_map=0
+compress/channel_pack=0
+mipmaps/generate=false
+mipmaps/limit=-1
+roughness/mode=0
+roughness/src_normal=""
+process/channel_remap/red=0
+process/channel_remap/green=1
+process/channel_remap/blue=2
+process/channel_remap/alpha=3
+process/fix_alpha_border=true
+process/premult_alpha=false
+process/normal_map_invert_y=false
+process/hdr_as_srgb=false
+process/hdr_clamp_exposure=false
+process/size_limit=0
+detect_3d/compress_to=1

docs/baselines/jajce_resource_grove_04_before.png.import

@@ -0,0 +1,40 @@
+[remap]
+
+importer="texture"
+type="CompressedTexture2D"
+uid="uid://ch6nx7rj4elit"
+path="res://.godot/imported/jajce_resource_grove_04_before.png-153834f7053f143a34b090dc21ac0d16.ctex"
+metadata={
+"vram_texture": false
+}
+
+[deps]
+
+source_file="res://docs/baselines/jajce_resource_grove_04_before.png"
+dest_files=["res://.godot/imported/jajce_resource_grove_04_before.png-153834f7053f143a34b090dc21ac0d16.ctex"]
+
+[params]
+
+compress/mode=0
+compress/high_quality=false
+compress/lossy_quality=0.7
+compress/uastc_level=0
+compress/rdo_quality_loss=0.0
+compress/hdr_compression=1
+compress/normal_map=0
+compress/channel_pack=0
+mipmaps/generate=false
+mipmaps/limit=-1
+roughness/mode=0
+roughness/src_normal=""
+process/channel_remap/red=0
+process/channel_remap/green=1
+process/channel_remap/blue=2
+process/channel_remap/alpha=3
+process/fix_alpha_border=true
+process/premult_alpha=false
+process/normal_map_invert_y=false
+process/hdr_as_srgb=false
+process/hdr_clamp_exposure=false
+process/size_limit=0
+detect_3d/compress_to=1

docs/benchmarks/LOADED_RESOURCE_DISCOVERY_01.md

@@ -68,7 +68,10 @@ simulation-LOD framework yet.
 Terrain3D foliage instances remain decorative unless an intentional stable-ID
 `ResourceNode` anchor binds simulation-owned state. A later placement workflow
 can author those anchors alongside visual instancing without making every tree
-an authoritative resource.
+an authoritative resource. That authored proof is now complete in
+[Jajce Resource Grove 04](../baselines/JAJCE_RESOURCE_GROVE_04.md): two nested
+finite anchors remain discoverable among three bounded decorative MultiMesh
+batches, including a real query that expands beyond its first local range.
 
 ## Capture command