diff --git a/docs/development.md b/docs/development.md
new file mode 100644
index 0000000..0d8deca
--- /dev/null
+++ b/docs/development.md
@@ -0,0 +1,56 @@
+# Development Notes
+
+## Local Commands
+
+Recommended:
+
+```bash
+uv sync --frozen
+uv run scanslicer
+```
+
+Alternative:
+
+```bash
+python -m scanslicer
+```
+
+## Packaging and Entry Points
+
+- Python package metadata: `pyproject.toml`
+- Console script: `scanslicer = scanslicer.entry:main`
+- Module entry: `python -m scanslicer`
+
+## High-Level Code Layout
+
+- `scanslicer/entry.py`: startup arguments + backend selection
+- `scanslicer/main.py`: main window and application bootstrap
+- `scanslicer/controller*.py`: user action logic
+- `scanslicer/ui_builders*.py`: widget construction
+- `scanslicer/canvas*.py`: preview rendering and interactive editing
+- `scanslicer/autoslicer*.py`: detection, auto-tune, and feedback engine
+- `scanslicer/params.py`: parameter schema and persistence
+- `scanslicer/slices.py`: box geometry utilities
+
+## Concurrency Model
+
+- Background work is executed via `QThreadPool`.
+- Thread pool is configured to a single worker thread to avoid overlapping detection/autotune tasks.
+- UI updates are dispatched through Qt signals.
+
+## Persistence Model Summary
+
+- Defaults and presets are JSON files.
+- Auto-tune feedback is a JSON list of historical entries.
+- Status log is plain text with session reset per app launch.
+
+All paths are configurable by environment variables (see `docs/runtime-config.md`).
+
+## Current Testing State
+
+- No automated test suite is currently present in this repository.
+- Recommended validation after changes:
+  - startup on Wayland and X11
+  - detection and save flow on representative sample scans
+  - auto-tune profile run and feedback write/read cycle
+  - AppImage and Docker startup sanity checks