docs: add README with quickstart guide

.github/workflows/publish.yml

@@ -31,7 +31,18 @@ jobs:
 
       - run: pnpm build
 
+      - name: Check if version already published
+        id: version-check
+        run: |
+          LOCAL_VERSION=$(node -p "require('./package.json').version")
+          if npm view @recoupable/cli@$LOCAL_VERSION version 2>/dev/null; then
+            echo "published=true" >> $GITHUB_OUTPUT
+          else
+            echo "published=false" >> $GITHUB_OUTPUT
+          fi
+
       - name: Publish to npm
+        if: steps.version-check.outputs.published == 'false'
         run: pnpm publish --no-git-checks
         env:
           NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

README.md

@@ -0,0 +1,78 @@
+# @recoupable/cli
+
+Command-line interface for the [Recoup](https://recoupable.com) platform.
+
+## Quick Start
+
+### Install
+
+```bash
+npm install -g @recoupable/cli
+```
+
+### Authenticate
+
+Set your API key as an environment variable:
+
+```bash
+export RECOUP_API_KEY=your-api-key
+```
+
+### Verify
+
+```bash
+recoup whoami
+```
+
+## Commands
+
+### Account
+
+```bash
+recoup whoami              # Show your account ID
+recoup whoami --json       # Output as JSON
+```
+
+### Artists
+
+```bash
+recoup artists list        # List your artists
+recoup artists list --json
+```
+
+### Chats
+
+```bash
+recoup chats list                    # List your chats
+recoup chats create --name "Topic"   # Create a new chat
+recoup chats create --artist <id>    # Create a chat with an artist
+```
+
+### Sandboxes
+
+```bash
+recoup sandboxes list                       # List your sandboxes
+recoup sandboxes create                     # Create a new sandbox
+recoup sandboxes create --command "ls -la"  # Create and run a command
+```
+
+### Organizations
+
+```bash
+recoup orgs list           # List your organizations
+```
+
+### Global Flags
+
+All commands support `--json` for machine-readable JSON output.
+
+## Configuration
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `RECOUP_API_KEY` | Yes | Your Recoup API key |
+| `RECOUP_API_URL` | No | API base URL (default: `https://recoup-api.vercel.app`) |
+
+## License
+
+MIT

package.json

@@ -7,7 +7,8 @@
     "recoup": "./dist/bin.cjs"
   },
   "files": [
-    "dist"
+    "dist",
+    "README.md"
   ],
   "scripts": {
     "build": "tsup",