docs: add final README and CONTRIBUTING

CONTRIBUTING.md

@@ -0,0 +1,82 @@
+# Contributing to Illuscape
+
+Thank you for helping make Inkscape more accessible to Illustrator migrants.
+
+## How to add a keyboard shortcut
+
+1. Open `config/keys/illustrator-cc.xml` and/or `config/keys/illustrator-cs6.xml`
+2. Add a `<bind>` element:
+   ```xml
+   <bind key="KEY" action="INKSCAPE_ACTION" modifiers="Primary,Shift" />
+   ```
+   Valid modifiers: `Primary` (Ctrl/Cmd), `Shift`, `Alt`. Omit `modifiers=""` for bare keys.
+3. Find Inkscape action names via `inkscape --action-list` on your system
+4. Update the shortcut table in `README.md`
+5. Update the shortcut comparison table in the spec if the shortcut differs between CC and CS6
+
+## How to add a color palette
+
+1. Create `config/palettes/YourPalette.gpl` following GPL format:
+   ```
+   GIMP Palette
+   Name: Your Palette Name
+   Columns: 8
+   #
+   255   0   0  Red
+   ...
+   ```
+2. Add the filename to `uninstall.sh`'s `remove_files()` function so it gets cleaned up
+3. The palette will be installed automatically by `install.sh` (it copies all `*.gpl` files)
+
+## How to add a document template
+
+1. Create an SVG at `config/templates/YourTemplate.svg`
+2. Include a `sodipodi:namedview` element with appropriate canvas settings
+3. Add the filename to `uninstall.sh`'s `remove_files()` function
+4. The template will be installed automatically by `install.sh` (copies all `*.svg` files)
+
+## How to add a preference
+
+Preferences live in `config/preferences-patch.xml`. The XML merge algorithm (in
+`scripts/merge_prefs.py`) does an upsert: it walks the patch tree, matches nodes
+by their `id` attribute, and sets only the attributes present in the patch. It
+never deletes nodes or attributes.
+
+To add a new preference:
+1. Find the relevant node in Inkscape's `preferences.xml` on a running install
+2. Add the node/attribute to `config/preferences-patch.xml` with the correct `id` values
+3. Write a test in `tests/test_merge_prefs.py` that verifies the attribute is set
+4. Run `conda run -n cf python3 -m pytest tests/test_merge_prefs.py -v` to verify
+
+## Running tests
+
+```bash
+# Python unit tests (merge algorithm)
+conda run -n cf python3 -m pytest tests/test_merge_prefs.py -v
+
+# Integration tests (requires bats-core)
+bats tests/test_install.bats
+
+# Validate all config files
+conda run -n cf python3 -c "
+from xml.etree import ElementTree as ET
+from pathlib import Path
+for f in [*Path('config/keys').glob('*.xml'), *Path('config/templates').glob('*.svg'),
+          *Path('config/symbols').glob('*.svg'), Path('config/preferences-patch.xml')]:
+    ET.parse(f)
+    print(f'OK {f}')
+"
+```
+
+## Commit format
+
+```
+feat: add <shortcut/palette/template>
+fix: correct <behavior>
+test: add test for <scenario>
+docs: update <section>
+```
+
+## License
+
+By contributing, you agree that your contributions are released under the MIT license.

README.md

@@ -6,6 +6,26 @@ Illuscape patches Inkscape's config to match Illustrator's keyboard shortcuts,
 workspace layout, scroll/zoom behavior, color palettes, and document templates —
 without modifying Inkscape itself.
 
+## What it does
+
+| Feature | Detail |
+|---------|--------|
+| Keyboard shortcuts | Adobe Illustrator CC or CS6 presets — your choice at install |
+| Scroll/zoom | Mouse wheel pans (not zooms); Ctrl+wheel zooms — matching Illustrator |
+| Canvas | White background, cyan guides, rubber-band selection (touching, not enclosed) |
+| Node handles | Square handles, rotation handles hidden until needed |
+| Palettes | Illustrator Defaults, Grays, and Earth Tones swatches |
+| Templates | Letter, A4, Web 1920x1080, Web 1280x720, Print CMYK Letter, Print CMYK A4 |
+| Symbols | Common symbol library (arrows, checkmark, star, cross) |
+| Recent files | 20 (matching Illustrator; Inkscape default is 4) |
+| Single-window mode | On by default |
+
+## Requirements
+
+- Inkscape 1.2 or later
+- Python 3.8+
+- Bash 4+
+
 ## Install
 
 ```bash
@@ -14,7 +34,21 @@ cd illuscape
 ./install.sh
 ```
 
-Follow the prompt to select your Illustrator era (CC or CS6), then open Inkscape.
+Follow the prompt to choose your Illustrator era (CC or CS6), then open Inkscape.
+
+### Non-interactive (for scripts / MenagerieOS)
+
+```bash
+./install.sh --preset=cc --yes
+# or
+./install.sh --preset=cs6 --yes
+```
+
+### Supported Inkscape installs
+
+- Native (apt, pacman, etc.)
+- Flatpak (`org.inkscape.Inkscape`)
+- Snap
 
 ## Uninstall
 
@@ -22,8 +56,46 @@ Follow the prompt to select your Illustrator era (CC or CS6), then open Inkscape
 ./uninstall.sh
 ```
 
-Your original Inkscape config is restored from backup.
+Your original Inkscape config is restored from the backup created at install time.
+
+## Tool mapping from Illustrator to Inkscape
+
+| Illustrator tool | Key | Inkscape equivalent |
+|-----------------|-----|---------------------|
+| Selection | V | Selection tool |
+| Direct Selection | A | Node tool |
+| Pen | P | Pen tool |
+| Pencil | N | Pencil tool |
+| Paintbrush | B | Calligraphy tool |
+| Type | T | Text tool |
+| Rectangle | M | Rectangle tool |
+| Ellipse | L | Ellipse tool |
+| Rotate | R | Transform > Rotate |
+| Scale | S | Transform > Scale |
+| Reflect | O | Transform > Flip |
+| Gradient | G | Gradient tool |
+| **Mesh** | **U** | **Mesh Gradient tool (direct equivalent)** |
+| Eyedropper | I | Dropper tool |
+| Zoom | Z | Zoom tool |
+| Hand | H / Space | Pan (Space held) |
+| Scissors | C | Scissors tool |
+| Eraser | Shift+E | Eraser tool |
+| Blob Brush | Shift+B | Spray tool (paint mode) |
+| Symbol Sprayer | Shift+S | Spray tool (clone mode) |
+| Live Paint | K | Paint Bucket tool |
+
+## Planned extensions (post-v1)
+
+- Artboards panel
+- Character Styles
+- Recolor Artwork
+- Object Styles
+- Export for Screens (1x/2x/3x batch)
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md).
 
 ## License
 
-MIT
+MIT — see [LICENSE](LICENSE).