From dc5487c96512ebc64370c8f6659b0fc1dc59a392 Mon Sep 17 00:00:00 2001
From: Mathieu Virbel <mat@meltingrocks.com>
Date: Tue, 10 Feb 2026 16:06:22 -0600
Subject: [PATCH] Add CLAUDE.md with project conventions and quick reference

---
 CLAUDE.md | 79 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 79 insertions(+)
 create mode 100644 CLAUDE.md

diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..13a24b2
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,79 @@
+# Greywall
+
+Sandboxing layer for GreyHaven that wraps commands in restrictive sandbox environments. Blocks network access by default (allowlist-based), restricts filesystem operations, and controls command execution. Supports macOS (sandbox-exec/Seatbelt) and Linux (bubblewrap + seccomp/Landlock/eBPF).
+
+## Build & Run
+
+```bash
+make setup          # install deps + lint tools (first time)
+make build          # compile binary (downloads tun2socks)
+make run            # build and run
+./greywall --help   # CLI usage
+```
+
+## Test
+
+```bash
+make test           # all unit + integration tests
+make test-ci        # with coverage and race detection (-race -coverprofile)
+GREYWALL_TEST_NETWORK=1 ./scripts/smoke_test.sh ./greywall  # smoke tests
+```
+
+## Lint & Format
+
+```bash
+make fmt            # format with gofumpt
+make lint           # golangci-lint (staticcheck, errcheck, gosec, govet, revive, gofumpt, misspell, etc.)
+```
+
+Always run `make fmt && make lint` before committing.
+
+## Project Structure
+
+```
+cmd/greywall/          CLI entry point
+internal/
+  config/              Configuration loading & validation
+  platform/            OS detection
+  sandbox/             Platform-specific sandboxing (~7k lines)
+    manager.go         Sandbox lifecycle orchestration
+    command.go         Command blocking/allow lists
+    linux.go           bubblewrap + bridges (ProxyBridge, DnsBridge)
+    macos.go           sandbox-exec Seatbelt profiles
+    linux_seccomp.go   Seccomp BPF syscall filtering
+    linux_landlock.go  Landlock filesystem control
+    linux_ebpf.go      eBPF violation monitoring
+    sanitize.go        Environment variable hardening
+    dangerous.go       Protected files/dirs lists
+pkg/greywall/          Public Go API
+docs/                  Full documentation
+scripts/               Smoke tests, benchmarks, release
+```
+
+## Code Conventions
+
+- **Language:** Go 1.25+
+- **Formatter:** `gofumpt` (enforced in CI)
+- **Linter:** `golangci-lint` v1.64.8 (config in `.golangci.yml`)
+- **Import order:** stdlib, third-party, local (`gitea.app.monadical.io/monadical/greywall`)
+- **Platform code:** build tags (`//go:build linux`, `//go:build darwin`) with `*_stub.go` for unsupported platforms
+- **Error handling:** custom error types (e.g., `CommandBlockedError`)
+- **Logging:** stderr with `[greywall:component]` prefixes
+- **Config:** JSON with comments (via `tidwall/jsonc`), optional pointer fields for three-state booleans
+
+## Dependencies
+
+4 direct deps: `doublestar` (glob matching), `cobra` (CLI), `jsonc` (config parsing), `golang.org/x/sys`.
+
+Runtime (Linux): `bubblewrap`, `socat`, embedded `tun2socks` v2.5.2.
+
+## CI
+
+GitHub Actions workflows: `main.yml` (build/lint/test on Linux+macOS), `release.yml` (GoReleaser + SLSA provenance), `benchmark.yml`.
+
+## Release
+
+```bash
+make release          # patch (v0.0.X)
+make release-minor    # minor (v0.X.0)
+```