From 41715d58c966706df633d60e7330bb7f4148cff3 Mon Sep 17 00:00:00 2001
From: Sweets Sweetman <sweetmantech@gmail.com>
Date: Tue, 10 Feb 2026 12:54:43 -0500
Subject: [PATCH] docs: add README with quickstart guide for npm landing page

Also skip publish in CI when version already exists on npm.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 .github/workflows/publish.yml | 11 +++++
 README.md                     | 78 +++++++++++++++++++++++++++++++++++
 package.json                  |  3 +-
 3 files changed, 91 insertions(+), 1 deletion(-)
 create mode 100644 README.md

diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml
index d813117..611d380 100644
--- a/.github/workflows/publish.yml
+++ b/.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 }}
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..68d8bb6
--- /dev/null
+++ b/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
diff --git a/package.json b/package.json
index f835f11..70ed403 100644
--- a/package.json
+++ b/package.json
@@ -7,7 +7,8 @@
     "recoup": "./dist/bin.cjs"
   },
   "files": [
-    "dist"
+    "dist",
+    "README.md"
   ],
   "scripts": {
     "build": "tsup",