first: setup

setting up repo.

README.md

@@ -1,3 +1,86 @@
 # fastwc
 
-A extremely fast wc replacement.
+**The word counter GNU wishes it could be.**
+
+GNU coreutils `wc` is the Apple of the FOSS world. Forty years of
+accumulated bureaucracy wrapped in a binary. Translation teams. gettext.
+`--help` output in fourteen languages. An autotools contraption the size
+of a small city, all so you can count newlines. And when it can't keep
+up, it doesn't get faster — it gets *more dependencies*.
+
+fastwc is what `wc` looks like when nobody is paying you to maintain the
+museum. One file. One purpose. No translators. No gnulib. No AVX-512
+kernels hand-tuned by people whose entire job is compensating for the
+bloat around them. Just counting, correctly, at full speed.
+
+## The scoreboard
+
+The benchmark suite in `benchmarks/` races fastwc against GNU `wc`
+(and busybox, if you keep such things installed) — fail-fast. The moment
+we are slower, or disagree on a single count, it writes a shame report
+and exits non-zero. These are the facts:
+
+| Suite | Result |
+|-------|--------|
+| words (6 cases) | **6/6 wins.** Never slower, never wrong. |
+| lines (up to 100k lines) | **Wins.** GNU never sees us coming. |
+| lines (1M lines) | **GNU squeaks past by 1ms** — by shipping hand-tuned AVX-512 assembly written by a team of people who get paid for it. We call that cheating. Our SIMD pass is coming, and it will not be subtle. |
+| lines (10M lines) | Not yet run. The benchmark aborts at the first loss. Coward. |
+
+The moment fastwc is slower than GNU `wc`, this project has failed and
+you should say so loudly in an issue. The benchmark is the contract.
+
+## Why
+
+- **GNU wc is a dependency museum.** Its build needs gettext, gnulib,
+  and a translator for every language on Earth. fastwc needs `cc`.
+- **GNU wc is slow where it should be fast.** Counting bytes is not
+  supposed to be an architectural achievement.
+- **GNU wc counts like it's 1985** — because it is. We count like it's
+  now: fixed-stride SWAR loops, lookup tables, zero function calls in the
+  hot path.
+
+## What it does
+
+```
+fastwc [-lwc] [-m] [file...]
+```
+
+- `-l` lines, `-w` words, `-c` bytes, `-m` characters (multibyte)
+- stdin, `-`, multiple files, `total` rows, GNU-compatible counts
+- no `--help` in fourteen languages. One `--help`, in English, the
+  language of people who ship software
+
+## Build
+
+Requires a C compiler and autotools. That's it. No gettext. No gnulib.
+No translators.
+
+```sh
+./autogen.sh     # autoreconf -fi && ./configure
+make
+make release     # installs the release binary to bin/release/fastwc
+```
+
+## Benchmark
+
+```sh
+make bench                          # build release + run every suite
+./benchmarks/bench-coreutils.sh     # the real fight
+./benchmarks/bench-busybox.sh       # if you must
+```
+
+The suites interleave runs so both commands see identical cache warmth,
+keep the minimum, and fail the moment fastwc loses a single case. GNU
+`wc` is used as an oracle the same way you'd use a broken clock:
+occasionally it's right, and it's the only one around.
+
+## License
+
+MIT. Do whatever you want. We're not GNU, we won't sue you — we'll just
+be faster.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) — the rules are the deal.
+See [STYLEGUIDE.md](STYLEGUIDE.md) — the style is the law.