README, CONTRIBUTING and Makefile

CONTRIBUTING.md

@@ -0,0 +1,70 @@
+# Contributing
+
+## Prerequisites
+
+- Rust toolchain
+- `make`
+- `pre-commit` for commit-time hooks
+- `pnpm` for site formatting checks
+- Linux with `xvfb-run` for integration tests
+
+Install site dependencies before running site checks:
+
+```bash
+pnpm --dir site install
+```
+
+## Repository Layout
+
+- `src/lib.rs` exposes the library target used by integration tests
+- `src/main.rs` is the thin CLI binary wrapper
+- `src/` holds production code and unit tests
+- `tests/` holds integration tests
+- `tests/support/` holds shared X11 and daemon helpers for integration coverage
+
+Keep integration-only helpers out of `src/`.
+
+## Local Validation
+
+The repo uses one local validation surface through `make`:
+
+```bash
+make fmt-check
+make lint
+make test-unit
+make test-integration
+make site-format-check
+make validate
+```
+
+`make validate` runs the full Phase 2 validation stack. It requires Linux, `xvfb-run`, and site dependencies to be installed.
+
+## Pre-commit Hooks
+
+Install the hook workflow once:
+
+```bash
+pre-commit install
+```
+
+Run hooks across the repo on demand:
+
+```bash
+pre-commit run --all-files
+```
+
+The hook config intentionally stays small:
+
+- Rust files use default `rustfmt`
+- Site files reuse the existing `site/` Prettier setup
+- Slower checks stay in CI or `make validate`
+
+## Integration Tests
+
+Integration coverage is Linux/X11-only in this phase. The supported local entrypoint is:
+
+```bash
+make test-integration
+```
+
+That command runs the top-level X11 integration tests under `xvfb-run` with one test thread so the shared display/session environment stays deterministic.

Makefile

@@ -0,0 +1,33 @@
+.PHONY: fmt fmt-check lint test-unit test-integration site-format-check validate
+
+fmt:
+	cargo fmt --all
+
+fmt-check:
+	cargo fmt --all --check
+
+lint:
+	cargo clippy --all-targets -- -D warnings
+
+test-unit:
+	cargo test --lib
+
+test-integration:
+	@if [ "$$(uname -s)" != "Linux" ]; then \
+		echo "Integration tests require Linux and xvfb-run."; \
+		exit 1; \
+	fi
+	@if ! command -v xvfb-run >/dev/null 2>&1; then \
+		echo "xvfb-run is required to execute integration tests."; \
+		exit 1; \
+	fi
+	XDG_SESSION_TYPE=x11 xvfb-run -a cargo test --test x11_runtime -- --test-threads=1
+
+site-format-check:
+	@if ! command -v pnpm >/dev/null 2>&1; then \
+		echo "pnpm is required for site formatting checks."; \
+		exit 1; \
+	fi
+	pnpm --dir site format:check
+
+validate: fmt-check lint test-unit test-integration site-format-check

README.md

@@ -59,6 +59,14 @@ deskctl focus "firefox"
 Client-daemon architecture over Unix sockets (NDJSON wire protocol). 
 The daemon starts automatically on first command and keeps the X11 connection alive for fast repeated calls.
 
+Source layout:
+
+- `src/lib.rs` exposes the shared library target
+- `src/main.rs` is the thin CLI wrapper
+- `src/` contains production code and unit tests
+- `tests/` contains Linux/X11 integration tests
+- `tests/support/` contains shared integration helpers
+
 ## Runtime Requirements
 
 - Linux with X11 session
@@ -89,6 +97,30 @@ deskctl doctor
 
 `deskctl` supports Linux X11 in this phase. Wayland and Hyprland are explicitly out of scope for the current runtime contract.
 
+## Workflow
+
+Local validation uses the root `Makefile`:
+
+```bash
+make fmt-check
+make lint
+make test-unit
+make test-integration
+make site-format-check
+make validate
+```
+
+`make validate` is the full repo-quality check and requires Linux with `xvfb-run` plus `pnpm --dir site install`.
+
+The repository standardizes on `pre-commit` for fast commit-time checks:
+
+```bash
+pre-commit install
+pre-commit run --all-files
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the full contributor guide.
+
 ## Acknowledgements
 
 - [@barrettruth](github.com/barrettruth) - i stole the website from [vimdoc](https://github.com/barrettruth/vimdoc-language-server)