CHORE: Add GitHub Actions CI and install/contributing docs

.github/workflows/check.yml

@@ -0,0 +1,56 @@
+name: check
+
+# GitHub Actions gate for contributors without Depot CI access.
+# .depot/workflows/check.yml remains the release gate (full `make check`
+# plus the site checks); this workflow covers the Go module only and
+# needs no Docker daemon, secrets, or network beyond module downloads.
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: check-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  go-check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - name: Set up Go
+        uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7.0.0
+        with:
+          go-version-file: go.mod
+          cache: true
+
+      - name: gofmt check
+        run: |
+          unformatted="$(gofmt -l .)"
+          if [ -n "$unformatted" ]; then
+            echo "gofmt: unformatted files:" >&2
+            echo "$unformatted" >&2
+            echo "run 'make format' and commit the result" >&2
+            exit 1
+          fi
+
+      - name: go vet
+        run: go vet ./...
+
+      - name: go build
+        run: go build ./...
+
+      # Docker integration tests self-skip unless TX9_TEST_DOCKER_IMAGE
+      # names an already-installed shell-capable image (see
+      # internal/docker), so this stays green and fast without a daemon.
+      # To run them locally:
+      #   docker pull ubuntu:24.04
+      #   TX9_TEST_DOCKER_IMAGE=ubuntu:24.04 go test ./internal/docker/
+      - name: go test
+        run: go test ./...

CONTRIBUTING.md

@@ -0,0 +1,67 @@
+# Contributing
+
+## Prerequisites
+
+- Go matching `go.mod` (currently Go 1.26) — verify with `go version`
+- Bash, Make, Python 3 (with PyYAML), `jq`, `gzip`, `tar`
+- ShellCheck v0.11.0 for `make check`
+- Docker, only for running boxes or the opt-in Docker integration tests
+- Node 22.18+ with npm, only for the `site/` Worker checks
+
+## Build
+
+```bash
+make tx9        # build ./bin/tx9 (VERSION=0.12.0 make tx9 to stamp a version)
+make dist       # cross-compile release binaries + checksums.txt into dist/
+go run .        # run without building; reports version "dev"
+```
+
+The CLI embeds its build context (`box.env`, `provision/`, `guest/`, `docker/`) at compile time, so rebuild after editing those files before testing `tx9 create`.
+
+## Test
+
+```bash
+make check      # full gate: syntax, ShellCheck, guest regressions, gofmt, go vet, go test ./...
+make format     # gofmt -w .
+go test -buildvcs=false ./...          # Go tests only
+go test -buildvcs=false -race ./...    # with the race detector
+```
+
+GitHub Actions (`.github/workflows/check.yml`) runs the gofmt check, `go vet ./...`, `go build ./...`, and `go test ./...` on pushes to `main` and every pull request. Depot CI (`.depot/workflows/check.yml`) additionally runs the full `make check` and the site checks, and remains the release gate.
+
+### Docker integration tests
+
+Go tests that need a real Docker daemon self-skip unless `TX9_TEST_DOCKER_IMAGE` names an already-installed image with `/bin/sh`, `cat`, `ls`, and `sleep`. They create only disposable containers and never mount host data:
+
+```bash
+docker pull ubuntu:24.04
+TX9_TEST_DOCKER_IMAGE=ubuntu:24.04 go test -buildvcs=false ./internal/docker/
+```
+
+Running boxes end to end (`tx9 create`, `tx9 enter`, `tx9 doctor`) also needs a running Docker daemon and is not part of CI.
+
+### Site checks
+
+```bash
+cd site
+npm ci --ignore-scripts
+npm run check && npm run format:check && npm run lint && npm test
+```
+
+## Makefile targets
+
+| Target         | What it does                                                                      |
+| -------------- | --------------------------------------------------------------------------------- |
+| `make tx9`     | Build `./bin/tx9` with the `VERSION` ldflag (`dev` by default)                    |
+| `make check`   | Full local gate: `syntax` + `lint` + `test` + `go-check`                          |
+| `make syntax`  | `bash -n` / `sh -n` / Python compile checks for shell and Python sources          |
+| `make lint`    | ShellCheck over guest, provision, docker, and test shell scripts                  |
+| `make test`    | Static contract checks and guest-script regressions under `tests/`                |
+| `make go-check`| gofmt check, `go vet ./...`, and `go test ./...`                                  |
+| `make format`  | Format all Go files with `gofmt -w`                                               |
+| `make dist`    | Cross-compile linux/darwin amd64+arm64 binaries and `checksums.txt` into `dist/`  |
+
+## Pull requests
+
+- Keep the diff focused, and run `make check` before opening a PR.
+- Note the `make check` result in the PR body, and call out any test you could not run.

README.md

@@ -22,6 +22,48 @@ For a stable HTTPS Executor origin and OAuth callbacks over a tailnet, see
 For host directories and NAS shares that should be visible inside an agent,
 see [Host mounts](docs/host-mounts.md).
 
+## Install
+
+Prerequisites:
+
+- Linux or macOS (amd64 or arm64) with a running Docker daemon — `docker info` should succeed. Creating a box needs internet access for the first image build.
+- To build from source: Go matching `go.mod` (currently Go 1.26).
+
+Install the latest release:
+
+```bash
+curl -fsSL https://tx9.col-agents.com/install | sh
+# installs to ~/.local/bin/tx9 (override with TX9_INSTALL_DIR)
+```
+
+Or with Go (reports version `dev`; use a release binary or `make tx9` for a stamped version):
+
+```bash
+go install github.com/davis7dotsh/tx9@latest
+```
+
+Or build from source:
+
+```bash
+git clone https://github.com/davis7dotsh/tx9.git
+cd tx9
+make tx9          # writes ./bin/tx9
+./bin/tx9
+```
+
+## Quickstart
+
+```bash
+tx9 create            # optional name: tx9 create my-box; first run builds the box image and can take a while
+tx9 list              # list boxes, status, and dashboard URLs
+tx9 enter my-box      # shell into the agent container
+tx9 doctor my-box     # health checks
+tx9 open my-box       # authenticated Executor dashboard URL
+tx9 delete my-box     # remove the box when done
+```
+
+Run `tx9` with no arguments for an overview of every box. See [Contributing](CONTRIBUTING.md) to build and test from source.
+
 ## Model
 
 ```text
@@ -261,6 +303,9 @@ disposable helper tests. The audit used an existing `ubuntu:24.04` image.
 
 `.depot/workflows/check.yml` runs the Go/guest and site checks through Depot
 CI for pushes to `main` and pull requests against any branch, including stacks.
+`.github/workflows/check.yml` runs `gofmt`, `go vet`, `go build`, and
+`go test ./...` on GitHub Actions for pushes to `main` and every pull request,
+with no Docker daemon required.
 
 ## Releases