1 files changed, 147 insertions, 0 deletions
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..ca3e63d
--- /dev/null
+++ b/README.md
@@ -0,0 +1,147 @@
+# WMAP Parser for C
+
+A parser for `wmap` formatted Wardley Map files in ANSI C, with 68k and PPC mac support.
+
+## Features
+
+- **ANSI C Compatible**: Works with older compilers and hardware
+- **Complete Coverage**: Supports all `wmap` entities (components, dependencies, notes, stages, groups, inertia, evolution)
+
+## Quick Start
+
+```c
+#include <wmap_parser.h>
+
+int main() {
+    // Parse from file
+    wmap_map_t* map = wmap_parse_file("example.wmap");
+    if (!map) {
+        printf("Failed to parse file\n");
+        return 1;
+    }
+
+    // Access parsed data
+    printf("Components: %d\n", map->component_count);
+    printf("Dependencies: %d\n", map->dependency_count);
+
+    // Access individual components
+    for (int i = 0; i < map->component_count; i++) {
+        printf("Component: %s at (%.2f, %.2f)\n",
+               map->components[i].name,
+               map->components[i].x,
+               map->components[i].y);
+    }
+
+    // Clean up
+    wmap_map_free(map);
+    return 0;
+}
+```
+
+## Build Instructions
+
+### Library Build
+```bash
+make              # Build release version -> ./build/release/
+make debug        # Build debug version -> ./build/debug/
+make test         # Test with example.wmap (uses current build)
+make benchmark    # Performance benchmark (100 iterations default)
+make -e ITERATIONS=1000 benchmark  # Custom iteration count
+```
+
+### Setting Configuration
+
+You can pass the CONFIGURATION environment variable to control which version
+is used. This applies to test and benchmark as well.
+```bash
+make -e CONFIGURATION=debug   # Debug build via environment variable
+```
+
+### Development
+```bash
+make debug        # Debug build with symbols
+make memtest      # Memory leak testing (uses debug build)
+make clean        # Remove all build artifacts (./build/ directory)
+make info         # Show build configuration and available targets
+```
+
+## Data Structures
+
+```c
+typedef struct {
+    wmap_component_t components[WMAP_MAX_COMPONENTS];
+    wmap_dependency_t dependencies[WMAP_MAX_DEPENDENCIES];
+    wmap_note_t notes[WMAP_MAX_NOTES];
+    wmap_stage_data_t stages[WMAP_MAX_STAGES];
+    wmap_group_t groups[WMAP_MAX_GROUPS];
+    wmap_inertia_t inertias[WMAP_MAX_INERTIAS];
+    wmap_evolution_t evolutions[WMAP_MAX_EVOLUTIONS];
+
+    int component_count;
+    int dependency_count;
+    // ... other counts
+} wmap_map_t;
+```
+
+### Component Structure
+```c
+typedef struct {
+    char name[64];        // Component name
+    float x, y;           // Position coordinates
+    wmap_shape_t shape;   // Shape (NONE, X, SQUARE, TRIANGLE, CIRCLE)
+} wmap_component_t;
+```
+
+### Dependency Structure
+```c
+typedef struct {
+    char from[64];        // Source component name
+    char to[64];          // Target component name
+    int is_arrow;         // 1 for ->, 0 for --
+} wmap_dependency_t;
+```
+
+## Memory Limits
+
+| Entity Type | Maximum Count |
+|-------------|---------------|
+| Components | 1024 |
+| Dependencies | 2048 |
+| Notes | 256 |
+| Groups | 128 |
+| Inertias | 256 |
+| Evolutions | 256 |
+| Name Length | 64 characters |
+| Text Length | 256 characters |
+
+## Performance
+
+- **Parsing Speed**: 32,000+ parses/second
+- **Memory Usage**: Fixed allocation, no dynamic memory during parsing
+- **File Size Limit**: 10MB maximum for safety
+- **Input Validation**: Automatic bounds checking and malformed input handling
+
+## API Reference
+
+### Core Functions
+
+```c
+// Parse from string
+wmap_map_t* wmap_parse_string(const char* input);
+
+// Parse from file
+wmap_map_t* wmap_parse_file(const char* filename);
+
+// Free parsed map
+void wmap_map_free(wmap_map_t* map);
+
+// Validate input size and format
+int wmap_validate_input(const char* input, size_t max_size);
+```
+
+### Error Handling
+
+- Functions return `NULL` on failure
+- Input validation prevents buffer overflows
+- Malformed lines are skipped, parsing continues
+- File size limits prevent excessive memory usage