diff --git a/README.md b/README.md
new file mode 100644
index 0000000..50529f8
--- /dev/null
+++ b/README.md
@@ -0,0 +1,70 @@
+# p — push jobs to worker
+
+`p` is a small command-line tool that pushes jobs to remote machines over SSH,
+with directory sync, job management, and attach/detach support.
+
+Instead of manually chaining `rsync`, `ssh`, and `tmux`, `p` wraps the whole
+flow into a single command and keeps track of your jobs.
+
+```
+$ p -- make
+Syncing to beefy...
+Job a3f2b091 started on beefy.
+ p-a3f2b091 | beefy                                            running
+...build output...
+--- done [exit 0] - press any key to detach ---
+Job a3f2b091 finished with exit code 0.
+```
+
+## Quick start
+
+```sh
+# Register a worker (checks for tmux and base64 automatically)
+p worker register user@myserver.local
+
+# Sync current directory and run a command on the default worker
+p -- make
+
+# Skip the sync (command needs no local files)
+p -n -- htop
+
+# Run on a specific worker
+p myserver -- cargo test --release
+
+# List running jobs
+p ls
+
+# Re-attach to a running job
+p attach a3f2b091
+
+# View captured output of any job (running or finished)
+p logs a3f2b091
+p logs -f a3f2b091     # follow live output
+
+# Kill a running job
+p stop a3f2b091
+
+# Copy a build artifact back to your machine
+p pull a3f2b091 target/release/mybinary ./
+
+# Remove a finished job and its remote files
+p rm a3f2b091
+
+# Remove all finished jobs at once
+p prune
+```
+
+## How it works
+
+1. `p` connects to the worker and creates `~/.p/jobs/<id>/` and `~/.p/workdirs/<id>/`
+2. Your current directory is synced to `~/.p/workdirs/<id>/` via `rsync`
+   (respects `.gitignore`; `.git/` is included so commands like `git describe` work)
+3. Your command runs inside a `tmux` session, with output captured to `output.log`
+4. You're attached to the session immediately — the status bar shows the job ID,
+   worker name, and live status
+5. When the job finishes, a prompt appears so you can read final output before
+   returning to your shell
+6. `Ctrl+B D` detaches at any time without killing the job;
+   `p attach <id>` reconnects later
+
+Job records are stored locally in `~/.local/share/p/jobs/<uuid>.json`.