docs: add CLAUDE.md project instructions

Co-Authored-By: Virgil <virgil@lethean.io>

CLAUDE.md

@@ -1,34 +1,42 @@
 # CLAUDE.md
 
-## Project Overview
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
 
-`core/go-container` provides container runtime management, LinuxKit image building, and portable dev environments. Three packages: root (container runtime + LinuxKit), devenv (dev environment orchestration), sources (image download from CDN/GitHub).
-
-## Build & Development
+## Build & Test
 
 ```bash
-go test ./...
-go test -race ./...
+go test ./...                              # all tests
+go test -race ./...                        # with race detector
+go test -run TestState_Add_Good ./...      # single test by name
+go test ./sources/                         # single package
+go test ./devenv/                          # single package
 ```
 
+No build step required -- this is a library. The `cmd/vm/` package registers CLI commands via `init()` into the parent `core/cli` binary.
+
+**Go workspace**: This module is part of a Go workspace (`~/Code/go.work`). Sibling modules (`go-io`, `go-config`, `go-i18n`, `cli`) are resolved via the workspace file during local development.
+
 ## Architecture
 
-Three packages:
+Three packages with a clear dependency direction: `devenv` -> `container` (root) -> `sources`.
 
-- Root (`container`) — Container lifecycle (start/stop/status), hypervisor abstraction (QEMU/Hyperkit), LinuxKit YAML config builder with embedded templates, state persistence
-- `devenv/` — Dev environment management: config loading, image management, shell access, test runner, serve mode, Claude integration. Depends on container/ and sources/
-- `sources/` — Image download sources: CDN and GitHub release fetchers with checksum verification
+- **Root (`container`)** -- Container lifecycle (`Manager` interface, `LinuxKitManager` implementation), hypervisor abstraction (`Hypervisor` interface with QEMU and Hyperkit implementations), JSON-persisted state (`~/.core/containers.json`), and LinuxKit template engine with embedded YAML templates and `${VAR:-default}` variable substitution.
 
-## Dependencies
+- **`devenv/`** -- `DevOps` orchestrator composing container and sources into a dev environment workflow: boot/stop/status, SSH shell and serial console access, project mounting via reverse SSHFS at `/app`, auto-detection of serve/test commands by project type, and sandboxed Claude sessions with auth forwarding.
 
-- `go-io` — File/process utilities
-- `go-config` — Configuration loading (devenv only)
-- `testify` — Test assertions
+- **`sources/`** -- `ImageSource` interface with CDN (HTTP GET) and GitHub (`gh release download`) implementations. `ImageManager` in devenv maintains a manifest tracking installed versions.
+
+## Key Patterns
+
+- **`io.Medium` abstraction** -- File system operations use `io.Medium` (from `go-io`) rather than `os` directly. Use `io.Local` for real file access. This enables test mocking.
+- **Compile-time interface checks** -- `var _ Interface = (*Impl)(nil)` (see `sources/cdn.go`, `sources/github.go`).
+- **Copy-on-read state** -- `State.Get()` and `State.All()` return copies to prevent data races.
+- **All persistent data** lives under `~/.core/` (containers.json, logs, images, config.yaml, known_hosts, linuxkit templates). `CORE_IMAGES_DIR` env var overrides the images directory.
 
 ## Coding Standards
 
-- UK English
-- All functions have typed params/returns
-- Tests use testify
-- Test naming: `_Good`, `_Bad`, `_Ugly` suffixes
-- License: EUPL-1.2
+- UK English (colour, organisation, honour)
+- Tests use testify; naming convention: `_Good` (happy path), `_Bad` (expected errors), `_Ugly` (edge cases)
+- Error wrapping: `fmt.Errorf("context: %w", err)`
+- Context propagation: all blocking operations take `context.Context` as first parameter
+- Licence: EUPL-1.2