first commit

ober

c99e7f3fe010d22cbfeac1822075704e7cf8a503

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..e8bc382
--- /dev/null
+++ b/README.md
@@ -0,0 +1,84 @@
+# chez-pcre2
+
+PCRE2 bindings for Chez Scheme, providing API parity with [gerbil-pcre2](../gerbil-pcre2/).
+
+## Requirements
+
+- Chez Scheme 10.x
+- libpcre2-8 (with pkg-config support)
+- GCC or compatible C compiler
+
+## Build
+
+```bash
+make          # builds pcre2_shim.so
+make test     # runs the test suite
+```
+
+## Usage
+
+```scheme
+(import (chez-pcre2 pcre2))
+
+;; Compile a pattern
+(define rx (pcre2-compile "(?P<year>\\d{4})-(?P<month>\\d{2})-(?P<day>\\d{2})"))
+
+;; Search
+(define m (pcre2-search rx "Today is 2024-03-15"))
+(pcre-match-group m 0)         ;=> "2024-03-15"
+(pcre-match-named m "year")    ;=> "2024"
+
+;; Replace
+(pcre2-replace "\\d+" "abc 42 def" "NUM")  ;=> "abc NUM def"
+(pcre2-replace-all "\\d+" "1 and 2" "X")   ;=> "X and X"
+
+;; Split
+(pcre2-split ",\\s*" "a, b, c")  ;=> ("a" "b" "c")
+
+;; Extract all matches
+(pcre2-extract "\\d+" "a1 b22 c333")  ;=> ("1" "22" "333")
+
+;; Boolean test
+(pcre2-matches? "^\\d+$" "12345")  ;=> #t
+```
+
+## API
+
+### Compilation
+- `(pcre2-compile pattern [options] [jit?])` - Compile a PCRE2 pattern
+- `(pcre2-regex pattern keyword: value ...)` - Compile with named options
+
+### Matching
+- `(pcre2-match rx subject [start])` - Full match (anchored)
+- `(pcre2-search rx subject [start])` - Search (unanchored)
+- `(pcre2-matches? rx subject [start])` - Boolean test
+
+### Match Access
+- `(pcre-match-group m [n])` - Get group n as string
+- `(pcre-match-named m name)` - Get named group
+- `(pcre-match-positions m [n])` - Get (start . end) positions
+- `(pcre-match->list m)` - All groups as list
+- `(pcre-match->alist m)` - Named groups as alist
+
+### Substitution
+- `(pcre2-replace rx subject replacement [start] [extended?])` - Replace first
+- `(pcre2-replace-all rx subject replacement [start] [extended?])` - Replace all
+
+### Iteration
+- `(pcre2-find-all rx subject [start])` - List of match objects
+- `(pcre2-extract rx subject [start])` - List of matched strings
+- `(pcre2-fold rx kons knil subject [start])` - Fold over matches
+- `(pcre2-split rx subject [limit])` - Split by pattern
+- `(pcre2-partition rx subject)` - Alternating non-match/match list
+
+### Utilities
+- `(pcre2-quote str)` - Escape metacharacters
+- `(pcre2-release! rx)` - Explicitly free resources
+
+### Pregexp-Compatible
+- `(pcre2-pregexp-match pattern subject [start] [end])`
+- `(pcre2-pregexp-match-positions pattern subject [start] [end])`
+- `(pcre2-pregexp-replace pattern subject replacement)`
+- `(pcre2-pregexp-replace* pattern subject replacement)`
+- `(pcre2-pregexp-quote str)`
+# chez-pcre2