1 files changed, 42 insertions, 0 deletions
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..6999bd6
--- /dev/null
+++ b/README.md
@@ -0,0 +1,42 @@
+# GoRayTracer
+
+CPU ray tracer in Go — a port of Peter Shirley's *Ray Tracing in One Weekend*. Renders spheres with material scattering and outputs a PNG.
+
+## What it does
+
+- **Geometry:** `Vec3D`/`Ray`, `Sphere` + `HitableList` (closest-hit search) — `hitable.go:19`, `camera.go:12`
+- **Camera:** pinhole with vertical FOV (90° by default) and aspect ratio — `camera.go:12`
+- **Materials:** `Lambertian` (diffuse), `Metal` (fuzzed reflection), `Dielectric` (glass, Schlick approximation) — `material.go:13`
+- **Rendering:** recursive `RayColor` with `MaxDepth=50`, `RaysPerPixel=10` stochastic anti-aliasing, gamma correction (`sqrt`) — `color.go:34`
+- **Output:** `Frame [1000][2000]Pixel` sky gradient background, saved as PNG via `image/png` — `image.go:19`
+
+Default scene (`main.go:35`): two `Lambertian` spheres (blue/red, radius `cos(π/4)`). Two alternative scenes are commented in `main.go:40` (metal/glass + ground sphere, and an animation loop).
+
+Constants in `main.go:11`: `Width=2000`, `Height=1000`, `TMin=0.001`, `TMax=1000`, `RaysPerPixel=10`, `MaxDepth=50`.
+
+## How to run
+
+Prerequisite: [mise](https://mise.jdx.dev/) (installs Go automatically) or Go 1.27+.
+
+```sh
+# with mise (recommended)
+mise install          # installs Go 1.27
+mise run run          # go run . → writes img.png (~5s, 2000×1000)
+mise run build        # builds ./goraytracer
+./goraytracer         # same as above
+
+# with Go directly
+go mod tidy
+go run .              # → img.png
+go build -o goraytracer . && ./goraytracer
+```
+
+Output is `img.png` (2000×1000 PNG, excluded by `.gitignore`). Check/lint:
+
+```sh
+mise run check        # go fmt + go fix -diff + go vet + go build
+```
+
+## Customizing
+
+Edit `main.go` to swap the `World` definition (uncomment the 4-sphere or animation blocks), or adjust `Width`/`Height`/`RaysPerPixel` for faster previews (e.g. 400×200).