docs: add comprehensive READMEs for root and language subdirectories

Author: markkovari

README.md

@@ -1,7 +1,97 @@
-Advent of Code collection
+# 🎄 Advent of Code Collection
 
-## LETSGOO :rocket:
+A comprehensive, multi-language collection of [Advent of Code](https://adventofcode.com/) solutions, standardized and optimized for performance and maintainability.
 
+## 🚀 Overview
 
+This repository contains solutions for various years of Advent of Code, implemented in multiple languages. The project is structured as a monorepo, grouping solutions by language and providing shared utilities and a unified testing interface.
 
-this is coming from a workspace
+### 📊 Implementation Matrix
+
+| Year | Rust 🦀 | Golang 🐹 | Zig ⚡ | Status |
+| :--- | :---: | :---: | :---: | :--- |
+| 2015 | ✅ | - | - | Complete |
+| 2017 | - | ✅ | - | Refactored |
+| 2018 | ✅ | - | - | Complete (Opt.) |
+| 2019 | ✅ | ✅ | - | Migrated from OCaml |
+| 2020 | ✅ | ✅ | - | Standardized |
+| 2021 | ✅ | - | ✅ | Migrated from C# |
+| 2022 | ✅ | - | - | Complete |
+| 2023 | ✅ | - | - | Migrated from Scala |
+| 2024 | - | ✅ | ✅ | Standardized |
+| 2025 | ✅ | - | - | In Progress |
+
+---
+
+## 🛠 Project Structure
+
+The repository follows a strict language-based organization:
+
+```text
+.
+├── golang/     # Go projects grouped by year
+├── inputs/     # Centralized puzzle inputs (Source of Truth)
+├── rust/       # Rust workspace (Cargo-based)
+├── zig/        # Zig projects grouped by year
+└── justfile    # Task runner for all languages
+```
+
+### 🗝 Key Features
+
+- **Standardized Architecture**: Every project follows a "Dispatcher" model, where a single entry point runs individual days.
+- **Unified Inputs**: All puzzle inputs are consolidated in a root `inputs/` folder, shared across all languages.
+- **Smart Test Caching**: Local and CI tests use a SHA-256 hashing strategy via `just` to skip tests that haven't changed.
+- **Optimized History**: The repository history is scrubbed of large build artifacts, making it extremely lean (~1.7MB).
+- **Fast CI**: GitHub Actions pipeline is optimized with conditional testing and language-specific caching.
+
+---
+
+## 🏎 Getting Started
+
+### Prerequisites
+
+- [Rust](https://www.rust-lang.org/) (stable/nightly)
+- [Go](https://go.dev/) (1.22+)
+- [Zig](https://ziglang.org/) (0.14.0+)
+- [Just](https://github.com/casey/just) (Task runner)
+
+### Running Tests
+
+We use `just` to provide a consistent interface across all languages.
+
+```bash
+# Run all tests across all languages (with smart caching)
+just test-all
+
+# Run only Rust tests
+just test-rust
+
+# Run only Go tests
+just test-go
+
+# Run only Zig tests
+just test-zig
+
+# Force a full re-run by cleaning the cache
+just clean-cache
+```
+
+### Adding New Solutions
+
+1.  Place your input in `inputs/<year>/<day>/prod.txt`.
+2.  Follow the standardized template for your chosen language (see language-specific READMEs).
+3.  Update the language dispatcher (`main.rs`, `main.go`, etc.).
+
+---
+
+## 📜 Documentation by Language
+
+- [Rust Documentation](./rust/README.md)
+- [Golang Documentation](./golang/README.md)
+- [Zig Documentation](./zig/README.md)
+
+---
+
+## ⚖️ License
+
+MIT © [Mark Kovari](https://github.com/markkovari)

golang/README.md

@@ -0,0 +1,55 @@
+# 🐹 Golang Advent of Code
+
+This directory contains Go solutions for Advent of Code, structured as independent modules sharing a common utility library.
+
+## 📁 Structure
+
+Each year is a separate module that uses a local `replace` directive to point to the shared `common` library.
+
+- **`common/`**: Shared interface and input resolution logic.
+- **`20XX/`**: Year-specific implementations and dispatchers.
+
+## 🚀 Standardized Day Template
+
+Every day is implemented in a separate file (e.g., `day01.go`) within the year directory:
+
+```go
+package main
+
+import (
+	"fmt"
+	"github.com/markkovari/advent_of_code/golang/common"
+)
+
+type DayXX struct{}
+
+func (d DayXX) Part1(input string) string {
+	return "result"
+}
+
+func (d DayXX) Part2(input string) string {
+	return "result"
+}
+```
+
+## 🧪 Running Solutions
+
+Go solutions are run through a centralized `main.go` in each year directory.
+
+```bash
+# Navigate to the year
+cd golang/2024
+
+# Run a specific day
+go run . 1
+
+# Run tests
+go test ./...
+```
+
+## 🛠 Adding a New Year
+
+1. Create a folder: `mkdir -p 20XX`.
+2. Initialize module: `go mod init github.com/markkovari/advent_of_code/golang/20XX`.
+3. Add `replace` to `go.mod`: `replace github.com/markkovari/advent_of_code/golang/common => ../common`.
+4. Create your `dayXX.go` files and a `main.go` dispatcher.

rust/README.md

@@ -0,0 +1,64 @@
+# 🦀 Rust Advent of Code
+
+This directory contains Rust solutions for Advent of Code, organized as a Cargo workspace.
+
+## 📁 Structure
+
+Each year is a separate crate within the workspace, depending on a shared `common` library.
+
+- **`common/`**: Shared utilities (input handling, geometry, BFS/Dijkstra algorithms).
+- **`20XX/`**: Year-specific implementations.
+- **`runner/`**: A master CLI tool to run any day from any year.
+
+## 🚀 Standardized Day Template
+
+Every day is implemented as a struct that satisfies the `Solution` trait:
+
+```rust
+use anyhow::Result;
+use aoc_common::Solution;
+
+pub struct DayXX;
+
+impl Solution for DayXX {
+    fn year(&self) -> u32 { 2023 }
+    fn day(&self) -> u32 { XX }
+
+    fn part1(&self, input: &str) -> Result<String> {
+        Ok("result".to_string())
+    }
+
+    fn part2(&self, input: &str) -> Result<String> {
+        Ok("result".to_string())
+    }
+}
+
+aoc_common::aoc_test!(DayXX);
+```
+
+## 🧪 Testing
+
+We use `insta` for snapshot testing and a custom `aoc_test!` macro for regression testing.
+
+### Local Execution
+```bash
+# Run all tests in the workspace
+cargo test
+
+# Run a specific year
+cargo test -p aoc-rust-2023
+
+# Run regression tests (including those ignored in CI)
+cargo test -- --ignored
+```
+
+### CI Environment
+In CI, heavy file-reading tests are marked as `#[ignore]` via the `advent_of_code_ci` flag to maintain pipeline speed.
+
+## 🛠 Adding a New Year
+
+1. Create a new folder: `mkdir -p 20XX/src`.
+2. Initialize `Cargo.toml` with `aoc-rust-20XX` name and dependency on `../common`.
+3. Add the folder to `rust/Cargo.toml` workspace members.
+4. Implement your days in `src/dayXX.rs`.
+5. Register them in `src/lib.rs` and `src/main.rs`.

zig/README.md

@@ -0,0 +1,49 @@
+# ⚡ Zig Advent of Code
+
+This directory contains Zig solutions for Advent of Code, optimized for performance and type safety.
+
+## 📁 Structure
+
+Solutions are grouped by year, with each year containing its own `build.zig` and source files.
+
+- **`20XX/`**: Year-specific implementations.
+- **`20XX/src/`**: Daily logic.
+
+## 🚀 Standardized Day Template
+
+Every day is implemented in `src/XX/main.zig`:
+
+```zig
+const std = @import("std");
+
+pub fn main() !void {
+    // Runtime execution logic
+}
+
+fn part1(input: []const u8) !u32 {
+    return 0;
+}
+
+test "day XX prod" {
+    const input = @embedFile("../../../inputs/2021/X/prod.txt");
+    try std.testing.expectEqual(@as(u32, 123), try part1(input));
+}
+```
+
+## 🧪 Testing
+
+We use Zig's built-in test runner to verify solutions at compile-time using `@embedFile`.
+
+```bash
+# Navigate to the year
+cd zig/2021
+
+# Run all tests
+zig build test
+```
+
+## 🛠 Adding a New Year
+
+1. Create a folder: `mkdir -p 20XX/src`.
+2. Create a `build.zig` that iterates over days and creates test steps.
+3. Implement your days in `src/XX/main.zig`.