From 47592911b92bd88dd8e5c614ab068433ff4c88a0 Mon Sep 17 00:00:00 2001
From: Harivansh Rathi <rathiharivansh@gmail.com>
Date: Wed, 25 Mar 2026 19:06:11 -0400
Subject: [PATCH] README, CONTRIBUTING and Makefile

---
 CONTRIBUTING.md | 70 +++++++++++++++++++++++++++++++++++++++++++++++++
 Makefile        | 33 +++++++++++++++++++++++
 README.md       | 32 ++++++++++++++++++++++
 3 files changed, 135 insertions(+)
 create mode 100644 CONTRIBUTING.md
 create mode 100644 Makefile

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..3c44332
--- /dev/null
+++ b/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.
diff --git a/Makefile b/Makefile
new file mode 100644
index 0000000..bb02037
--- /dev/null
+++ b/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
diff --git a/README.md b/README.md
index a1405d7..2438381 100644
--- a/README.md
+++ b/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)