udpated docs

README.md

@@ -0,0 +1,32 @@
+# Mathy
+
+Mathy is a playground for experimenting with streamed arithmetic on very large integers. The core `mathstream` package keeps big numbers on disk and operates on them chunk by chunk, which lets you manipulate values that would be impractical to materialize in memory. Around that library live a handful of experiments, utilities, and tests that explore different ways to work with big-number data.
+
+## What's Here
+- `mathstream/` – Streaming big-int helpers (`StreamNumber`, arithmetic primitives, garbage collection utilities). See `mathstream/README.md` for an in-depth guide.
+- `collatz_ui/` + `collatz.py` – A curses dashboard that visualizes Collatz walks. The UI pushes work onto a background thread so the main loop can keep the interface responsive while mathstream evaluates each step.
+- `stupid.py` – Experimental Collatz-based encoder/decoder that maps ASCII message chunks to Collatz seeds and replays the sequence to recover the text.
+- `seed_start.py` – Utility for seeding `start.txt` with huge streamed additions sourced from randomness or deterministic sequences.
+- `tests/` – Sample digit files used by the regression script in `test.py`.
+
+## Getting Started
+```bash
+python -m venv venv
+source venv/bin/activate
+pip install -e .
+```
+
+From there you can explore the components:
+- Run the regression checks: `python test.py`
+- Launch the Collatz dashboard: `python collatz.py`
+- Try the Collatz encoder prototype: `python stupid.py`
+- Seed the running total file: `python seed_start.py --seed 100 --mode seq`
+
+All streamed results land in `instance/log/`. If you need a clean slate, call `mathstream.clear_logs()` or delete that directory between runs.
+
+## Experiments and Next Steps
+- **Streaming worker** – The Collatz UI's worker thread (`collatz_ui/app.py`) demonstrates how to keep long-running streamed computations off the main event loop.
+- **Collatz encoding** – `stupid.py` currently encodes a message by turning ASCII blocks into integers and treating the first block as the Collatz seed. Extending this to use the full sequence (or to target specific steps) is an open avenue for exploration.
+- **More tests** – `test.py` covers the primary mathstream operations. Add pytest cases or property tests under `tests/` as new behaviours land.
+
+Pull requests are welcome—especially around new streamed operations, smarter Collatz decoding strategies, and additional high-volume math experiments.

WORK.md

@@ -2,6 +2,8 @@
 
 Figured I’d write down how the whole thing is wired, more like a brain dump than polished docs. If you’re diving in to fix something, this should save you a bunch of spelunking.
 
+> New top-level `README.md` now mirrors the high-level pitch, cross-links experiments (`collatz_ui`, `stupid.py`, `seed_start.py`), and lists quick-start commands (`pip install -e .`, `python test.py`, etc.). Treat this file as the deep dive into the mathstream core.
+
 ## Directory map (so you know where to poke)
 
 ```