add localization uncertainty recovery example

Add examples/navigation/10_localization_uncertainty_recovery.py. The robot
wakes up with a bimodal pose belief over two mirror cells that produce
identical landmark distances. The agent detects the high entropy, drives
toward the symmetric landmark to break the ambiguity, then switches one-way
to A* goal navigation after the belief collapses.

Cover the loop with a smoke test asserting success, recovery_count >= 1,
final entropy below threshold, and that both localize and go_to_goal
states appear in the trace. Register a GIF maker and the rendered GIF.

Update README, examples/README.md, examples/navigation/README.md,
docs/learning_paths.md, docs/status.md, and docs/plan.md to reflect the
new example, GIF, and test counts (23 examples, 22 GIFs, 65 tests).

Author: rsasaki0109

README.md

@@ -11,10 +11,10 @@ robotics loops rather than standalone algorithms.
 
 ## Current Status
 
-- 22 runnable examples
+- 23 runnable examples
 - 20 learning-path roadmap examples
-- 21 README GIFs generated from runnable examples
-- 59 smoke and regression tests
+- 22 README GIFs generated from runnable examples
+- 65 smoke and regression tests
 - Core dependencies only: `numpy` and `matplotlib`
 
 See `docs/status.md` for the implementation snapshot and `docs/plan.md` for
@@ -118,9 +118,9 @@ These GIFs are generated from the runnable examples, not separate animations.
 | --- | --- |
 | ![A grid robot reduces pose and map uncertainty with active sensing.](docs/assets/gifs/active_slam_toy.gif) | ![A point robot repeatedly replans short-horizon controls around a moving obstacle.](docs/assets/gifs/interactive_mpc.gif) |
 
-| Blocked path recovery |
-| --- |
-| ![A grid robot detects a newly blocked path, steps back, marks the blocked cell, and replans.](docs/assets/gifs/blocked_path_recovery.gif) |
+| Blocked path recovery | Localization uncertainty recovery |
+| --- | --- |
+| ![A grid robot detects a newly blocked path, steps back, marks the blocked cell, and replans.](docs/assets/gifs/blocked_path_recovery.gif) | ![A grid robot starts with a bimodal pose belief, drives toward a landmark to break the symmetry, then navigates to the goal.](docs/assets/gifs/localization_uncertainty_recovery.gif) |
 
 ### Embodied AI
 

docs/assets/gifs/localization_uncertainty_recovery.gif

@@ -16,6 +16,7 @@
 4. `examples/navigation/06_belief_based_navigation.py`
 5. `examples/navigation/07_active_slam_toy.py`
 6. `examples/navigation/08_interactive_mpc.py`
+7. `examples/navigation/10_localization_uncertainty_recovery.py`
 
 ## Manipulation Intelligence
 

docs/learning_paths.md

@@ -8,11 +8,11 @@ first-run experience small, fast, and failure-aware.
 
 The repository currently has:
 
-- 22 runnable examples
+- 23 runnable examples
 - 20 numbered learning-path examples
-- 2 extra examples outside the original learning-path roadmap
-- 21 generated README GIFs
-- 59 smoke and regression tests
+- 3 extra examples outside the original learning-path roadmap
+- 22 generated README GIFs
+- 65 smoke and regression tests
 - GitHub Actions CI for Python 3.10, 3.11, and 3.12
 - core dependencies limited to `numpy` and `matplotlib`
 - optional Gymnasium-style adapters for `GridWorld2D`,
@@ -81,6 +81,10 @@ Recent completed work:
 - Focused adapter tests were added covering reset shape, step shape, action
   decoding, success termination, timeout truncation, and recoverable
   `blocked_path` failure.
+- `examples/navigation/10_localization_uncertainty_recovery.py` was added.
+  The agent wakes up with a bimodal pose belief, takes information actions
+  toward the symmetric landmark, then switches one-way to goal navigation
+  after the belief collapses. A GIF and smoke test cover the loop.
 
 The next agent should not redo those items. If any of them seem missing, first
 check the current branch and latest pulled commit.
@@ -89,8 +93,9 @@ Recommended next task:
 
 1. Pick the next adapter or example from the "Next candidates" list under
    Priority 3 and Priority 4. A continuous-control wrapper such as
-   `MovingObstacleWorld`, or `examples/navigation/10_localization_uncertainty_recovery.py`,
-   are both reasonable next steps.
+   `MovingObstacleWorld`, or a manipulation belief-grasp example
+   (`examples/manipulation/08_belief_grasp_selection.py`) are both reasonable
+   next steps.
 2. Keep the package/example boundary the same as the `BlockedPathWorld` work:
    environment in `pir/worlds/`, agent + policy + run loop in the example.
 3. Adapter tests should be added before broadening the adapter API further.
@@ -226,21 +231,25 @@ Acceptance criteria:
 
 ### Priority 4: Add The Next Example Tier
 
-Goal: grow from 22 examples toward 30 examples without losing readability.
+Goal: grow from 23 examples toward 30 examples without losing readability.
+
+Already done from the previous tier:
+
+- `examples/navigation/10_localization_uncertainty_recovery.py` — pose
+  uncertainty -> information action -> resume goal navigation.
 
 Recommended next examples:
 
 | Priority | Example | Area | Loop |
 | --- | --- | --- | --- |
-| 1 | `examples/navigation/10_localization_uncertainty_recovery.py` | navigation | pose uncertainty -> information action -> recover |
-| 2 | `examples/manipulation/08_belief_grasp_selection.py` | manipulation | pose belief -> grasp choice -> failure update |
-| 3 | `examples/manipulation/09_active_viewpoint_for_grasp.py` | manipulation | choose view -> reduce occlusion -> grasp |
-| 4 | `examples/embodied_ai/21_object_permanence_toy.py` | embodied AI | object disappears -> memory persists -> search |
-| 5 | `examples/embodied_ai/22_where_did_i_see_it.py` | embodied AI | memory query -> revisit place -> act |
-| 6 | `examples/world_models/23_model_error_recovery.py` | world model | prediction failure -> update model -> recover |
-| 7 | `examples/navigation/24_information_gain_navigation.py` | navigation | goal progress vs information gain |
-| 8 | `examples/manipulation/25_clear_path_before_pick.py` | manipulation | precondition failure -> clear obstacle -> pick |
-| 9 | `examples/navigation/27_multi_agent_avoidance.py` | navigation | observe agents -> avoid -> replan |
+| 1 | `examples/manipulation/08_belief_grasp_selection.py` | manipulation | pose belief -> grasp choice -> failure update |
+| 2 | `examples/manipulation/09_active_viewpoint_for_grasp.py` | manipulation | choose view -> reduce occlusion -> grasp |
+| 3 | `examples/embodied_ai/21_object_permanence_toy.py` | embodied AI | object disappears -> memory persists -> search |
+| 4 | `examples/embodied_ai/22_where_did_i_see_it.py` | embodied AI | memory query -> revisit place -> act |
+| 5 | `examples/world_models/23_model_error_recovery.py` | world model | prediction failure -> update model -> recover |
+| 6 | `examples/navigation/24_information_gain_navigation.py` | navigation | goal progress vs information gain |
+| 7 | `examples/manipulation/25_clear_path_before_pick.py` | manipulation | precondition failure -> clear obstacle -> pick |
+| 8 | `examples/navigation/27_multi_agent_avoidance.py` | navigation | observe agents -> avoid -> replan |
 
 Selection rule:
 

docs/plan.md

@@ -5,10 +5,10 @@ see what exists, what is verified, and what should come next.
 
 ## Snapshot
 
-- Runnable examples: 22
+- Runnable examples: 23
 - Learning-path roadmap examples: 20
-- README GIFs: 21
-- Smoke and regression tests: 59
+- README GIFs: 22
+- Smoke and regression tests: 65
 - Core dependencies: `numpy`, `matplotlib`
 - Contributor extra: `pip install -e ".[dev]"`
 - CI: Python 3.10, 3.11, 3.12
@@ -29,7 +29,7 @@ goal-command example. The numbered 20-example roadmap is tracked in
 | Area | Examples | Main concepts |
 | --- | ---: | --- |
 | Runtime | 2 | smallest observe-act-observe loop, trace replay |
-| Navigation | 8 | reactive avoidance, dynamic obstacles, replanning, exploration, belief, active SLAM, MPC, recovery |
+| Navigation | 9 | reactive avoidance, dynamic obstacles, replanning, exploration, belief, active SLAM, MPC, recovery, localization recovery |
 | Manipulation | 7 | retry, reactive grasping, IK servo, moving target reaching, search, push recovery, suction sorting |
 | Embodied AI | 4 | controlled goals, memory, POMDP search, tiny VLA loop |
 | World models | 1 | action-conditioned dynamics, prediction error, model update, replanning |

docs/status.md

@@ -24,6 +24,7 @@ Run any example headless with its `--no-render` flag when available.
 | `navigation/07_active_slam_toy.py` | `python examples/navigation/07_active_slam_toy.py` | act to reduce map and pose uncertainty |
 | `navigation/08_interactive_mpc.py` | `python examples/navigation/08_interactive_mpc.py` | predict -> control -> replan |
 | `navigation/09_blocked_path_recovery.py` | `python examples/navigation/09_blocked_path_recovery.py` | detect blocked path -> recover -> replan |
+| `navigation/10_localization_uncertainty_recovery.py` | `python examples/navigation/10_localization_uncertainty_recovery.py` | ambiguous pose -> information action -> resume goal |
 
 ## Manipulation