diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..ee444fe
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,106 @@
+# mcltspice
+
+MCP server for LTspice circuit simulation automation.
+
+## Project Layout
+
+```
+src/mcltspice/       # Package source (server.py is the FastMCP entry point)
+tests/               # pytest suite (asyncio_mode=auto)
+docs/                # Starlight docs site (Astro + Docker)
+```
+
+## Development
+
+```bash
+uv run pytest tests/ -m "not integration"   # Unit tests (no LTspice needed)
+uv run pytest tests/ -m integration          # Integration tests (needs Wine + LTspice)
+uv run ruff check src/ tests/               # Lint
+uv run mcltspice                             # Run MCP server locally
+```
+
+## Versioning
+
+Date-based: `YYYY.MM.DD` with `.N` suffix for same-day patches (e.g. `2026.02.14.1`).
+
+Bump in `pyproject.toml` before publishing.
+
+## Publishing to PyPI
+
+```bash
+rm -rf dist/ && uv build
+uv publish --token "$(python3 -c "
+import configparser; c=configparser.ConfigParser()
+c.read('$HOME/.pypirc'); print(c['pypi']['password'])
+")"
+```
+
+The sdist is kept slim (~100KB) via `[tool.hatch.build.targets.sdist]` include list in pyproject.toml.
+
+Verify: `uv pip install --dry-run --refresh mcltspice==<version>`
+
+## Production Deployment
+
+### Git Remotes
+
+| Remote   | URL                                              | Purpose          |
+|----------|--------------------------------------------------|------------------|
+| `origin` | `git@git.supported.systems:warehack.ing/mcltspice.git` | Private (primary) |
+| `mcp`    | `git@git.supported.systems:MCP/mcltspice.git`          | Org mirror        |
+
+Push to both: `git push origin main && git push mcp main`
+
+### Docs Site (mcltspice.warehack.ing)
+
+The production docs site runs as a Docker container behind caddy-docker-proxy on a remote server.
+
+**Server access:**
+```bash
+ssh -A warehack-ing@mcltspice.warehack.ing
+```
+
+**Project location on server:** `~/mcltspice/`
+
+**Deploy steps:**
+```bash
+ssh -A warehack-ing@mcltspice.warehack.ing
+cd mcltspice
+git pull
+cd docs
+make prod
+```
+
+`make prod` builds the Astro static site inside Docker, serves it via an internal Caddy on `:8080`, and the external caddy-docker-proxy handles TLS at `mcltspice.warehack.ing`.
+
+**Server .env** (already configured, don't change):
+```
+COMPOSE_PROJECT_NAME=mcltspice-docs
+MODE=prod
+SITE_DOMAIN=mcltspice.warehack.ing
+```
+
+**One-liner from local machine:**
+```bash
+ssh -A warehack-ing@mcltspice.warehack.ing "cd mcltspice && git pull && cd docs && make prod"
+```
+
+### Full Release Checklist
+
+1. Bump version in `pyproject.toml`
+2. Commit and push to both remotes
+3. Build and publish to PyPI
+4. SSH to server, pull, `make prod`
+5. Verify: `curl -sI https://mcltspice.warehack.ing/`
+
+## Data Shape Convention
+
+`raw_parser.py` returns `data` with shape `(n_vars, n_points)` -- each row is one variable's full time series. Index as `data[var_idx]` (row), never `data[:, var_idx]` (column).
+
+## svg_plot.py
+
+Pure SVG generation, no matplotlib. Key internals:
+- `_render_subplot()` draws grid, axes, labels, and one data path
+- `_build_path_d()` maps data arrays to SVG path coordinates
+- `plot_timeseries_multi()` overlays multiple traces using `_render_subplot` for the first trace + raw `<path>` elements for the rest
+- `_OVERLAY_COLORS` is an 8-color palette; `_render_legend()` draws the legend box
+- `from __future__ import annotations` is used here (safe -- no FastMCP tool definitions in this file)