@@ -43,7 +43,7 @@ In this project we use Jupyter/IPython Notebooks to showcase the algorithms in t
 - Proofread the notebooks for grammar mistakes, typos, or general errors.
 - Move visualization and unrelated to the algorithm code from notebooks to `notebook_utils.py` (a file used to store code for the notebooks, like visualization and other miscellaneous stuff). Make sure the notebooks still work and have their outputs showing!
 - Replace the `%psource` magic notebook command with the function `psource` from `notebook_utils.py` where needed. Examples where this is useful are a) when we want to show code for algorithm implementation and b) when we have consecutive cells with the magic keyword (in this case, if the code is large, it's best to leave the output hidden).
-- Add the function `pseudocode(algorithm_name)` in algorithm sections. The function prints the pseudocode of the algorithm. You can see some example usage in [`knowledge.ipynb`](https://github.com/aimacode/aima-python/blob/master/knowledge.ipynb).
+- Add the function `pseudocode(algorithm_name)` in algorithm sections. The function prints the pseudocode of the algorithm. You can see some example usage in [`knowledge_current_best.ipynb`](https://github.com/aimacode/aima-python/blob/master/notebooks/knowledge_current_best.ipynb).
 - Edit existing sections for algorithms to add more information and/or examples.
 - Add visualizations for algorithms. The visualization code should go in `notebook_utils.py` to keep things clean.
 - Add new sections for algorithms not yet covered. The general format we use in the notebooks is the following: First start with an overview of the algorithm, printing the pseudocode and explaining how it works. Then, add some implementation details, including showing the code (using `psource`). Finally, add examples for the implementations, showing how the algorithms work. Don't fret with adding complex, real-world examples; the project is meant for educational purposes. You can of course choose another format if something better suits an algorithm.
 
@@ -16,18 +16,17 @@ The 4th edition of the book is out now in 2020, and thus we are updating the cod
 **Edition policy (3rd vs 4th).** As [Peter Norvig stated](https://github.com/aimacode/aima-python/issues/1188#issuecomment-641669882), we are *not* maintaining two parallel editions — all new work should move toward the 4th edition. Concretely:
 
 - The **4th edition is canonical**: new algorithms, fixes and pseudocode references should follow the 4e numbering and content.
-- Some modules still come in pairs (e.g. `agents.py` / `agents4e.py`). The unsuffixed modules are the primary, fully-tested base that the notebooks and tests use today; the `*4e.py` modules carry 4e-specific ports and algorithms not present in the 3e files. We are **converging on a single version per module**; until that migration is complete, prefer adding 4e content over extending the 3e-only versions.
-- New 4th-edition-only material (e.g. `deep_learning4e.py`, `game_theory4e.py`, `perception4e.py`) lives directly in its 4e module.
+- The 3e/4e split is **done**: there is now a **single version per module** (no `*4e.py` files remain). The old 3e/4e pairs have been merged — the canonical implementation was kept and any genuinely-new 4e algorithms were folded in — and the 4e-only modules (`deep_learning.py`, `game_theory.py`, `making_simple_decisions.py`, `perception.py`) were de-suffixed. Add new 4e content directly to the relevant module.
 
 
 
 # Structure of the Project
 
-When complete, this project will have Python implementations for all the pseudocode algorithms in the book, as well as tests and examples of use. For each major topic, such as `search`, we provide the following  files:
+When complete, this project will have Python implementations for all the pseudocode algorithms in the book, as well as tests and examples of use. The code is organised into three top-level folders:
 
-- `search.ipynb` and `search.py`: Implementations of all the pseudocode algorithms, and necessary support functions/classes/data. The `.py` file is generated automatically from the `.ipynb` file; the idea is that it is easier to read the documentation in the `.ipynb` file.
-- `search_XX.ipynb`: Notebooks that show how to use the code, broken out into various topics (the `XX`).
-- `tests/test_search.py`: A lightweight test suite, using `assert` statements, designed for use with [`py.test`](http://pytest.org/latest/), but also usable on their own.
+- **`aima/`** — the importable Python package: one module per major topic (e.g. `aima/search.py`) with the implementations of the pseudocode algorithms and their support functions/classes/data.
+- **`notebooks/`** — the Jupyter notebooks that explain and demonstrate the code (e.g. `notebooks/search.ipynb`), plus the per-chapter `notebooks/chapterNN/` demos. Each notebook starts with a small bootstrap cell so it runs correctly from the `notebooks/` folder (it `chdir`s to the repo root so `from aima import ...` and the `aima-data/`/`images/` paths resolve).
+- **`tests/`** — a lightweight test suite (e.g. `tests/test_search.py`), using `assert` statements, designed for use with [`py.test`](http://pytest.org/latest/) but also usable on their own.
 
 # Python 3.9 and up
 
 
@@ -1,5 +1,20 @@
 {
  "cells": [
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# notebooks live under notebooks/; run from the repo root so that\n",
+    "# `from aima import ...` and the cwd-relative aima-data/ and images/ paths resolve.\n",
+    "import os, sys\n",
+    "if os.path.basename(os.getcwd()) == 'notebooks':\n",
+    "    os.chdir('..')\n",
+    "if os.getcwd() not in sys.path:\n",
+    "    sys.path.insert(0, os.getcwd())"
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},
 
@@ -1,5 +1,20 @@
 {
  "cells": [
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# notebooks live under notebooks/; run from the repo root so that\n",
+    "# `from aima import ...` and the cwd-relative aima-data/ and images/ paths resolve.\n",
+    "import os, sys\n",
+    "if os.path.basename(os.getcwd()) == 'notebooks':\n",
+    "    os.chdir('..')\n",
+    "if os.getcwd() not in sys.path:\n",
+    "    sys.path.insert(0, os.getcwd())"
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {
 
@@ -1,5 +1,20 @@
 {
  "cells": [
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# notebooks live under notebooks/; run from the repo root so that\n",
+    "# `from aima import ...` and the cwd-relative aima-data/ and images/ paths resolve.\n",
+    "import os, sys\n",
+    "if os.path.basename(os.getcwd()) == 'notebooks':\n",
+    "    os.chdir('..')\n",
+    "if os.getcwd() not in sys.path:\n",
+    "    sys.path.insert(0, os.getcwd())"
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},
 
@@ -1,5 +1,20 @@
 {
  "cells": [
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# notebooks live under notebooks/; run from the repo root so that\n",
+    "# `from aima import ...` and the cwd-relative aima-data/ and images/ paths resolve.\n",
+    "import os, sys\n",
+    "if os.path.basename(os.getcwd()) == 'notebooks':\n",
+    "    os.chdir('..')\n",
+    "if os.getcwd() not in sys.path:\n",
+    "    sys.path.insert(0, os.getcwd())"
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},
@@ -628,7 +643,7 @@
    "source": [
     "## N-QUEENS\n",
     "\n",
-    "The N-queens puzzle is the problem of placing N chess queens on an N\u00d7N chessboard in a way such that no two queens threaten each other. Here N is a natural number. Like the graph coloring problem, NQueens is also implemented in the csp module. The **NQueensCSP** class inherits from the **CSP** class. It makes some modifications in the methods to suit this particular problem. The queens are assumed to be placed one per column, from left to right. That means position (x, y) represents (var, val) in the CSP. The constraint that needs to be passed to the CSP is defined in the **queen_constraint** function. The constraint is satisfied (true) if A, B are really the same variable, or if they are not in the same row, down diagonal, or up diagonal. "
+    "The N-queens puzzle is the problem of placing N chess queens on an N×N chessboard in a way such that no two queens threaten each other. Here N is a natural number. Like the graph coloring problem, NQueens is also implemented in the csp module. The **NQueensCSP** class inherits from the **CSP** class. It makes some modifications in the methods to suit this particular problem. The queens are assumed to be placed one per column, from left to right. That means position (x, y) represents (var, val) in the CSP. The constraint that needs to be passed to the CSP is defined in the **queen_constraint** function. The constraint is satisfied (true) if A, B are really the same variable, or if they are not in the same row, down diagonal, or up diagonal. "
    ]
   },
   {
@@ -2775,7 +2790,7 @@
        "version_minor": 0
       },
       "text/plain": [
-       "interactive(children=(IntSlider(value=0, description='iteration', max=20), Output()), _dom_classes=('widget-in\u2026"
+       "interactive(children=(IntSlider(value=0, description='iteration', max=20), Output()), _dom_classes=('widget-in…"
       ]
      },
      "metadata": {},
@@ -2789,7 +2804,7 @@
        "version_minor": 0
       },
       "text/plain": [
-       "interactive(children=(ToggleButton(value=False, description='Visualize'), ToggleButtons(description='Extra Del\u2026"
+       "interactive(children=(ToggleButton(value=False, description='Visualize'), ToggleButtons(description='Extra Del…"
       ]
      },
      "metadata": {},
@@ -2924,7 +2939,7 @@
        "version_minor": 0
       },
       "text/plain": [
-       "interactive(children=(IntSlider(value=0, description='iteration', max=473, step=0), Output()), _dom_classes=('\u2026"
+       "interactive(children=(IntSlider(value=0, description='iteration', max=473, step=0), Output()), _dom_classes=('…"
       ]
      },
      "metadata": {},
@@ -2938,7 +2953,7 @@
        "version_minor": 0
       },
       "text/plain": [
-       "interactive(children=(ToggleButton(value=False, description='Visualize'), ToggleButtons(description='Extra Del\u2026"
+       "interactive(children=(ToggleButton(value=False, description='Visualize'), ToggleButtons(description='Extra Del…"
       ]
      },
      "metadata": {},
@@ -3008,7 +3023,7 @@
        "version_minor": 0
       },
       "text/plain": [
-       "interactive(children=(IntSlider(value=0, description='iteration', max=27, step=0), Output()), _dom_classes=('w\u2026"
+       "interactive(children=(IntSlider(value=0, description='iteration', max=27, step=0), Output()), _dom_classes=('w…"
       ]
      },
      "metadata": {},
@@ -3022,7 +3037,7 @@
        "version_minor": 0
       },
       "text/plain": [
-       "interactive(children=(ToggleButton(value=False, description='Visualize'), ToggleButtons(description='Extra Del\u2026"
+       "interactive(children=(ToggleButton(value=False, description='Visualize'), ToggleButtons(description='Extra Del…"
       ]
      },
      "metadata": {},
 
@@ -1,5 +1,20 @@
 {
  "cells": [
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# notebooks live under notebooks/; run from the repo root so that\n",
+    "# `from aima import ...` and the cwd-relative aima-data/ and images/ paths resolve.\n",
+    "import os, sys\n",
+    "if os.path.basename(os.getcwd()) == 'notebooks':\n",
+    "    os.chdir('..')\n",
+    "if os.getcwd() not in sys.path:\n",
+    "    sys.path.insert(0, os.getcwd())"
+   ]
+  },
   {
    "cell_type": "markdown",
    "id": "07e68a51",
 
@@ -1,5 +1,20 @@
 {
  "cells": [
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# notebooks live under notebooks/; run from the repo root so that\n",
+    "# `from aima import ...` and the cwd-relative aima-data/ and images/ paths resolve.\n",
+    "import os, sys\n",
+    "if os.path.basename(os.getcwd()) == 'notebooks':\n",
+    "    os.chdir('..')\n",
+    "if os.getcwd() not in sys.path:\n",
+    "    sys.path.insert(0, os.getcwd())"
+   ]
+  },
   {
    "cell_type": "markdown",
    "id": "eec33447",
 
@@ -1,5 +1,20 @@
 {
  "cells": [
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# notebooks live under notebooks/; run from the repo root so that\n",
+    "# `from aima import ...` and the cwd-relative aima-data/ and images/ paths resolve.\n",
+    "import os, sys\n",
+    "if os.path.basename(os.getcwd()) == 'notebooks':\n",
+    "    os.chdir('..')\n",
+    "if os.getcwd() not in sys.path:\n",
+    "    sys.path.insert(0, os.getcwd())"
+   ]
+  },
   {
    "cell_type": "markdown",
    "id": "172aa32c",
 
@@ -1,5 +1,20 @@
 {
  "cells": [
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# notebooks live under notebooks/; run from the repo root so that\n",
+    "# `from aima import ...` and the cwd-relative aima-data/ and images/ paths resolve.\n",
+    "import os, sys\n",
+    "if os.path.basename(os.getcwd()) == 'notebooks':\n",
+    "    os.chdir('..')\n",
+    "if os.getcwd() not in sys.path:\n",
+    "    sys.path.insert(0, os.getcwd())"
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},
@@ -1666,4 +1681,4 @@
  },
  "nbformat": 4,
  "nbformat_minor": 1
-}
+}