add README documentation

README.md

@@ -0,0 +1,47 @@
+# 6soz
+
+A 6502 / 6510 CPU emulator engine, disassembler, and system architecture library written in [Zig](https://ziglang.org/).
+
+## Features
+
+- **MOS 6502 & MOS 6510 CPU Core**: Emulation of instruction execution, registers, and memory addressing modes.
+- **ALU & Opcodes**: Full support for standard and illegal/undocumented opcodes.
+- **Disassembler**: Instruction disassembler for 6502 assembly inspection.
+- **Conformance Suite**: Built-in verification and test suite.
+- **Modular Architecture**: Clean module organization separating CPU emulation, system platforms, and frontends.
+
+## Requirements
+
+- **Zig**: `0.16.0` or newer
+
+## Getting Started
+
+### Building
+
+Build the project using Zig:
+
+```bash
+zig build
+```
+
+### Running Tests
+
+Run the full unit and conformance test suite:
+
+```bash
+zig build test
+```
+
+## Project Structure
+
+```text
+src/
+├── cpu/          # MOS 6502/6510 CPU implementation, opcode decoders, disassembler
+├── system/       # System-level integrations (e.g., NES, C64)
+├── platform/     # Platform abstractions
+└── frontend/     # UI / CLI frontends
+```
+
+## License
+
+This project is licensed under the [MIT License](LICENSE).