docs: rewrite README, DOCUMENTATION, and CHANGELOG — too robotic, rewrote from scratch

README.md

@@ -1,59 +1,70 @@
 # ASCII 3D Renderer
 
-An advanced software-based 3D text renderer pipeline written purely in C11. 
+A 3D text rendering engine that runs entirely in your terminal, written in C. Type any word and watch it spin in 3D with proper lighting, shading, and depth — all drawn with ASCII characters.
 
-By avoiding proprietary graphics stacks, this engine demonstrates foundational rendering principles—like Z-buffer processing, Phong illumination models, matrices integration, and anti-aliasing sweeps—executing cleanly inside standard POSIX terminal boundaries.
+No OpenGL, no GPU, no graphics libraries. Just math, a framebuffer made of characters, and ANSI escape codes.
 
-## Architecture & Documentation
+## What it does
 
-Review [DOCUMENTATION.md](DOCUMENTATION.md) for deeper knowledge of subsystems, technical boundaries, and lighting logic optimizations employed in the source code.
-Review [CHANGELOG.md](CHANGELOG.md) for version release tracking constraints.
+You give it a string like `HELLO`, and it renders each letter as a 3D object by extruding a built-in 5×7 bitmap font along the Z-axis. A Blinn-Phong lighting model (with a 3-point light setup — key, fill, and rim) calculates the brightness at each surface point, which then gets mapped to an ASCII character from a density palette like `.:-=+*#%@`.
 
-## Technical Feats
+The whole thing runs as an interactive TUI. You can type new text on the fly, change render modes, toggle color output, adjust rotation speed — all without restarting.
 
-- Real-time `termios`-driven TUI with non-blocking key capture for dynamic typing
-- Mathematically robust 3D normal computations leveraging 2D glyph extrusion passes
-- Configurable AA (multi-sampling) and shading density metrics per-pixel
-- Support for RGB Truecolor processing directly through terminal escape sequences
-- Strictly isolated C11 components minimizing external dependencies 
+## Docs
 
-## Rapid Compilation via Makefile
+- [DOCUMENTATION.md](DOCUMENTATION.md) — how the rendering pipeline works, module breakdown, and how things fit together.
+- [CHANGELOG.md](CHANGELOG.md) — version history.
+
+## Features
+
+- Interactive TUI with non-blocking input via `termios` — no need to restart to change text or settings
+- 3D normal estimation from 2D glyph bitmaps using neighbor-vacancy checks
+- Multiple render modes: solid, wireframe, points, and shaded
+- Anti-aliasing via multi-sample jittered rays
+- Color output: monochrome, 16-color ANSI, 256-color ANSI, or full RGB truecolor
+- Four different ASCII shade palettes (standard, extended 70-char, block characters, minimal)
+- 60 FPS target with frame timing via `CLOCK_MONOTONIC` and `nanosleep`
+
+## Building
+
+You need `clang` and `make`. The only library dependency is `libm` (math).
 
 ```bash
-# Deploys standard -O3 and -flto compiler optimizations
+# optimized build with -O3 and LTO
 make release
 
-# Run directly, observing standard parameters
+# debug build with AddressSanitizer and UBSan
+make debug
+
+# run it
 ./bin/ascii3d
 ```
 
-## Interactive TUI Controls
+There's also `make profile` for gprof, `make analyze` for cppcheck, and `make format` for clang-format.
 
-Upon executing, the renderer spins into an active TTY session:
+## Controls
 
-- **Type Alphanumeric Characters** – Immediately replaces the internal 3D model with your input in real-time.
-- `[w]` and `[s]` – Increase / decrease rotational velocity.
-- `[Space]` – Toggle rotation engine pause constraints.
-- `[m]` – Cycles between topology rendering (Wireframe -> Shaded Pipeline -> Solid Geometry -> Points).
-- `[c]` – Switch between rendering spaces (Mono Base -> 16/256 ANSI -> Full Truecolor mapping).
-- `[p]` – Change ASCII shading dictionaries on the fly.
-- `[q]` or `ESC` – Safely detaches the IO hooks and shuts the process down cleanly.
+Once it's running, you're in an interactive session:
 
-## Execution Options
+| Key | What it does |
+|-----|-------------|
+| Any letter/number | Changes the displayed 3D text in real-time |
+| `w` / `s` | Speed up / slow down rotation |
+| `Space` | Pause or resume rotation |
+| `m` | Cycle render mode (Solid → Wireframe → Points → Shaded) |
+| `c` | Cycle color mode (Mono → ANSI 16 → ANSI 256 → Truecolor) |
+| `p` | Cycle ASCII shade palette |
+| `q` or `ESC` | Quit cleanly |
 
-Command-line invocations to bypass or configure TUI session states:
+## Command-line examples
 
 ```bash
-# Tumbling rotation utilizing Truecolor ANSI standards
+# Rotate on all axes, truecolor mode
 ./bin/ascii3d -a -c3 WORLD
 
-# Quality override with heavy Anti-Aliasing pipeline 
+# Anti-aliasing on, 1.5x oversampling, 256-color mode
 ./bin/ascii3d -A -q1.5 -c2 HQ
 
-# Show full parameter dictionary
+# Show all options
 ./bin/ascii3d -h
-```
-
-## Contributing
-
-The codebase attempts strict functional modularity. We accept modifications introducing new geometry patterns, deeper PBR emulation methods, or expanded rendering logic assuming complete dependency evasion.
+```