diff --git a/clean-architecture-visualizer/README.md b/clean-architecture-visualizer/README.md
new file mode 100644
index 0000000..63fe938
--- /dev/null
+++ b/clean-architecture-visualizer/README.md
@@ -0,0 +1,57 @@
+# Clean Architecture Visualizer (web app)
+
+This directory contains the web application for the Clean Architecture Visualizer project. It exposes a browser-based UI for exploring Clean Architecture “engines” and their interactions.
+
+## Prerequisites
+
+- Node.js and npm installed.
+- Git installed (if you are cloning the repo).
+
+## Installation
+
+Clone the repository (if you have not already):
+
+```bash
+git clone https://github.com/paulgries/Clean-Architecture-Visualizer.git
+cd Clean-Architecture-Visualizer
+```
+
+Install dependencies for the web app:
+
+```bash
+cd clean-architecture-visualizer
+npm install
+npm run build
+npm link
+```
+
+## Running the app
+
+Start the development server:
+
+```bash
+cave view <filepath>
+```
+
+This will start the frontend (and any backend services configured in this package). Check the console output for the local URL (typically http://localhost:5173 or similar, depending on the dev setup).
+
+## Running tests
+
+To run the backend/unit tests:
+
+```bash
+npm test
+```
+
+The Jest configuration for the backend lives in jest.config.js, and backend tests are under tests/backend/.
+
+## Project structure
+
+Key subdirectories and files:
+- src/ – Backend/core logic for the visualizer.
+- frontend/ – Frontend code for the UI.
+- tests/backend/ – Backend tests.
+- examples/ – Example projects and data used with the visualizer.
+- package.json – Scripts and dependencies for this package.
+
+For higher-level context about the overall project, see the top-level README.md in the repository root.
diff --git a/clean-architecture-visualizer/package-lock.json b/clean-architecture-visualizer/package-lock.json
index 45ac811..50f58d5 100644
--- a/clean-architecture-visualizer/package-lock.json
+++ b/clean-architecture-visualizer/package-lock.json
@@ -9,16 +9,18 @@
       "version": "1.0.0",
       "license": "MIT",
       "dependencies": {
-        "commander": "^14.0.2",
-        "typescript": "^5.9.3"
+        "chalk": "^5.6.2",
+        "commander": "^14.0.2"
       },
       "bin": {
-        "cave": "dist/app/index.js"
+        "cave": "dist/src/app/index.js"
       },
       "devDependencies": {
         "@types/jest": "^30.0.0",
         "@types/node": "^25.0.10",
-        "jest": "^30.2.0"
+        "jest": "^30.2.0",
+        "ts-jest": "^29.4.6",
+        "typescript": "^5.9.3"
       }
     },
     "node_modules/@babel/code-frame": {
@@ -1665,15 +1667,6 @@
         "node": ">=6.0.0"
       }
     },
-    "node_modules/brace-expansion": {
-      "version": "2.0.2",
-      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-2.0.2.tgz",
-      "integrity": "sha512-Jt0vHyM+jmUBqojB7E1NIYadt0vI0Qxjxd2TErW94wDz+E2LAm5vKMXXwg6ZZBTHPuUlDgQHKXvjGBdfcF1ZDQ==",
-      "dev": true,
-      "dependencies": {
-        "balanced-match": "^1.0.0"
-      }
-    },
     "node_modules/braces": {
       "version": "3.0.3",
       "resolved": "https://registry.npmjs.org/braces/-/braces-3.0.3.tgz",
@@ -3552,18 +3545,6 @@
         "node": ">=6"
       }
     },
-    "node_modules/minimatch": {
-      "version": "9.0.5",
-      "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-9.0.5.tgz",
-      "integrity": "sha512-G6T0ZX48xgozx7587koeX9Ys2NYy6Gmv//P89sEte9V9whIapMNF4idKxnW2QtCcLiTWlb/wfCabAtAFWhhBow==",
-      "dev": true,
-      "dependencies": {
-        "brace-expansion": "^2.0.1"
-      },
-      "engines": {
-        "node": "*"
-      }
-    },
     "node_modules/minimist": {
       "version": "1.2.8",
       "resolved": "https://registry.npmjs.org/minimist/-/minimist-1.2.8.tgz",