first commit, initial layout and some ideas I want to implement, included my linked list impl

README.md

@@ -0,0 +1,122 @@
+### Core “make C nicer” utilities
+
+1. **`xmalloc/xcalloc/xrealloc/xstrdup` (header: `xalloc.h`)**
+
+   * Teaches: error handling patterns, `errno`, consistent OOM behavior.
+
+2. **Arena allocator (header: `arena.h`)**
+
+   * `arena_init`, `arena_alloc`, `arena_reset`, `arena_free`
+   * Teaches: alignment, bump allocators, lifetime-based allocation.
+
+3. **Dynamic buffer / string builder (header: `buf.h`)**
+
+   * `buf_reserve`, `buf_append`, `buf_appendf`
+   * Teaches: amortized growth, `vsnprintf`, safe formatting.
+
+4. **Slice + spans (header: `span.h`)**
+
+   * `typedef struct { uint8_t* p; size_t n; } span_u8;` etc.
+   * Teaches: safer APIs than raw pointers, length-carrying.
+
+5. **Hash map (header: `hashmap.h`)** (string→void* or string→u64)
+
+   * Teaches: hashing, open addressing, tombstones, resizing.
+
+6. **Bitset (header: `bitset.h`)**
+
+   * `bitset_set/clear/test`, `bitset_find_first_zero`
+   * Teaches: word operations, popcount/ctz if you want.
+
+### C11 correctness features
+
+7. **Compile-time assertions & type checks (header: `ctassert.h`)**
+
+   * Wrap `_Static_assert`, plus some `_Generic` helpers.
+   * Teaches: compile-time constraints, “making invalid states unrepresentable”.
+
+8. **`_Generic` logging macros (header: `log.h`)**
+
+   * `LOG_INFO("x=%d", x)` with file/line, optional type-based formatting helpers.
+   * Teaches: variadic macros, `_Generic`, ergonomics.
+
+9. **Defer/cleanup pattern (header: `defer.h`)**
+
+   * Macro that runs cleanup at scope end (via `goto` pattern).
+   * Teaches: structured cleanup in C, error paths.
+
+10. **Optional result type (header: `result.h`)**
+
+* `typedef struct { int ok; int err; T value; } result_T;` pattern.
+* Teaches: explicit error handling, no hidden global state.
+
+### Concurrency & atomics (C11’s “real” new power)
+
+11. **Atomic reference counting (header: `refcnt.h`)**
+
+* `ref_inc/ref_dec` with destructor callback.
+* Teaches: `stdatomic.h`, memory ordering (start with seq_cst, then learn relax/acq_rel).
+
+12. **Lock-free SPSC ring buffer (header: `ring_spsc.h`)**
+
+* Single-producer/single-consumer queue.
+* Teaches: atomics, cache friendliness, correctness reasoning.
+
+13. **Thread pool (header: `threadpool.h`)** using `threads.h`
+
+* `tp_init`, `tp_submit`, `tp_join`, `tp_destroy`
+* Teaches: `thrd_t`, `mtx_t`, `cnd_t`, work queues.
+
+14. **Once-init & singletons (header: `once.h`)**
+
+* Use `once_flag` / `call_once` (or implement if platform lacks).
+* Teaches: init races, safe global setup.
+
+### Parsing / CLI tools (you’ll actually use these)
+
+15. **Argument parser (header: `argparse.h`)**
+
+* `--long`, `-s`, combined short flags, `--key=value`
+* Teaches: string parsing, API design, test cases.
+
+16. **INI parser (header: `ini.h`)**
+
+* Minimal: sections, key=value, comments.
+* Teaches: parsing state machines, callbacks.
+
+17. **CSV reader/writer (header: `csv.h`)**
+
+* Correct quoting/escaping.
+* Teaches: edge cases, streaming parsing.
+
+18. **Path utilities (header: `path.h`)**
+
+* `path_join`, `path_dirname`, `path_basename`, normalize `..` and `.`
+* Teaches: portability pitfalls, careful string ops.
+
+### Systems-ish building blocks
+
+19. **File mapping / buffered reader (header: `io.h`)**
+
+* Portable-ish wrapper for “read whole file”, “iter lines”, “atomic write via temp+rename”.
+* Teaches: robust file I/O patterns, error handling.
+
+20. **Timing + profiling helpers (header: `timeutil.h`)**
+
+* `now_ns()`, `stopwatch`, `scope_timer` macro
+* Teaches: `timespec_get`, measurement pitfalls, microbenchmark hygiene.
+
+---
+
+## A suggested “crash course” order (so it builds)
+
+1–3 (xalloc/arena/buf) → 7–10 (static assert, generic, cleanup, results) → 15 (argparse) → 19 (io) → 16–18 (parsers) → 11–14 (atomics/threads) → 5–6 (hashmap/bitset) → 20 (timing) → 12/13 (ring + threadpool, as capstone)
+
+---
+
+## Two capstone tool ideas that use a lot of the above
+
+* **`logscan`**: fast log parser + filter + histogram (buf + argparse + csv + hashmap + timeutil)
+* **`dedupe`**: file deduplicator by hashing chunks (io + hashmap + arena + threadpool)
+
+---