diff --git a/README.md b/README.md
index 603f1e2..925de93 100644
--- a/README.md
+++ b/README.md
@@ -1,42 +1,82 @@
-# QueryLanguage - [Work-in-Progress]
+# QueryLanguage — Learning Branch
 
-for auto generate type from DB run
-`npm run generate-types`
+> **This repo is a sandbox, not a product.**
+> It was written as a trial-and-error exercise to learn how to build a JQL-style query DSL — lexer, parser, AST visitor, and SQL compilation — before taking on the real implementation. Expect incomplete features and a few dead ends.
 
-this project is the second part of a larger project aiming to provide
-an easy to implement solution for filtering and query data in a JQL like style
+The "real thing" will be built as a separate project, informed by what was learned here.
 
-part one: "Filter Manger"  
-https://github.com/tedwin007/FilterManger
+## What I was trying to learn
 
-## Analyze query
+- How to design a small grammar and express it with [Chevrotain](https://chevrotain.io/) (tokens, CST parser rules, visitors).
+- How to turn a parsed tree into an intermediate representation that a downstream compiler can consume.
+- How to wire that into [TypeORM](https://typeorm.io/) and go from parsed query → executable SQL.
+- How to auto-generate entity classes from a live database schema.
 
-Example: the query
+## The query shape being explored
 
-```
-(user bday > "1/1/1998") And (user gender = "F")
-```
+    (Entity prop operator value) [And|Or (Entity prop operator value) ...]
 
-Is being analyzed to see if the query's structure is valid.
+Examples:
 
-future planning:
+    (User age > 18)
+    (User gender = "F") And (User age > 18)
 
-- validate the existing of entities and their props (not in this package scope)
-- transforming the query into any DB query you use (partially in this package scope)
+Flow:
 
-more examples :
+    input string
+      → lexer (Chevrotain tokens)
+      → parser (CST)
+      → visitor (normalized IR)
+      → query builder (SQL string)
 
-`(Asset 1 > 10)`
+## What works
 
-will throw the following msg due to wrong statement structure
-(entity prop cannot be numeric)
+- Tokenizing and parsing the grammar above.
+- Visiting the CST into a flat list of `VisitedStatement`s joined by conjunctions.
+- Compiling that list into a `SELECT * FROM <entity> WHERE …` string.
+- Validating entity and property names against a supplied metadata map.
+- Generating TypeORM entity classes from a database via `typeorm-model-generator`.
 
-`MismatchedTokenException: Expecting token of type --> Identifier <-- but found --> '1' <--`
+## Running it
 
-## Query Builder
+    npm install
+    npm test          # Jasmine suite
+    npm run dev       # Nodemon on src/index.ts
+    npm run tsc       # Type-check + build to main/
 
-included in this project is TypeORM (https://typeorm.io/) and (typeorm-model-generator) libs
-this enables you to auto-generate TS types (TypeORM specifically) from your DB by running
-`npm run generate-types`
-You can use .env file to configure your db connection
-or you simply follow the CLI steps
+### Generating entities from a DB (optional)
+
+Configure `.env`:
+
+    HOST=localhost
+    DB_NAME=my_db
+    USER_NAME=my_user
+    PASSWORD=***
+    DB_TYPE=mysql
+    OUTPUT_PATH=./src/lib/ORM/
+
+Then:
+
+    npm run generate-types
+
+## Project layout
+
+    src/
+    ├── index.ts
+    └── lib/
+        ├── lexer/       # Chevrotain tokens
+        ├── parser/      # CST parser rules
+        ├── visitor/     # CST → IR
+        └── ORM/
+            ├── db-connector/    # TypeORM DataSource factory
+            ├── query-builder/   # IR → SQL
+            ├── entities/        # Generated entity classes
+            └── scripts/         # generate-types.js
+
+## Related
+
+- [FilterManager](https://github.com/tedwin007/FilterManger) — part one, the consumer of the DSL this branch was exploring.
+
+## Status
+
+Archived as a reference. The production implementation lives elsewhere (or will). Please don't depend on this package.