docs: README overhaul

README.md

@@ -1,171 +1,190 @@
-# Partiful CLI
+![Banner](https://ghrb.waren.build/banner?header=partiful-cli+%F0%9F%8E%89&subheader=Manage+Partiful+events+from+your+terminal&bg=0d1117&color=f0f6fc&support=false)
 
-JSON-first, agent-friendly CLI for managing [Partiful](https://partiful.com) events from the command line.
+# partiful-cli
 
-## Installation
+> Manage [Partiful](https://partiful.com) events from your terminal. JSON-first, script-friendly.
 
-```bash
-npm install -g .
-# or link for development
-npm link
-```
-
-Requires **Node.js 18+**.
-
-## Auth Setup
-
-Partiful doesn't offer a public API. This CLI uses the same internal API that the web app uses, authenticated via Firebase tokens.
-
-### Bookmarklet Flow
+[![npm version](https://img.shields.io/npm/v/partiful-cli)](https://www.npmjs.com/package/partiful-cli)
+[![license](https://img.shields.io/npm/l/partiful-cli)](LICENSE)
+[![node](https://img.shields.io/node/v/partiful-cli)](package.json)
 
-1. Log into [partiful.com](https://partiful.com) in your browser
-2. Run the bookmarklet extractor or use browser DevTools to capture your auth tokens
-3. Save credentials:
+## Try it now
 
 ```bash
-partiful auth save --token <accessToken> --refresh <refreshToken> --user-id <userId>
+npx partiful-cli --help
 ```
 
-4. Verify:
+## Install
 
 ```bash
-partiful auth status
+# Install globally
+npm install -g partiful-cli
+
+# Or run without installing
+npx partiful-cli <command>
+
+# Or clone and link
+git clone https://github.com/KalebCole/partiful-cli && cd partiful-cli
+npm install && npm link
 ```
 
-Tokens auto-refresh when expired.
+## Features
+
+- 🎉 **Events** — create, list, get, update, cancel
+- 👥 **Guests** — list RSVPs, send invites
+- 📱 **Blasts** — text all your guests at once
+- 🎨 **Posters** — browse and attach poster images
+- 📋 **Templates** — save and reuse event configs
+- 📦 **Bulk** — batch create/update from JSON
+- 👀 **Watch** — live RSVP polling with NDJSON output
+- 🔄 **Clone** — duplicate events to new dates
+- 📤 **Export** — event + guests to JSON or CSV
+- 🩺 **Doctor** — diagnose auth and setup issues
 
 ## Quick Start
 
 ```bash
-# List upcoming events
-partiful events list
+# 1. Authenticate
+partiful auth login +12065551234
 
-# Get event details
-partiful events get <eventId>
+# 2. Verify setup
+partiful doctor
 
-# Create an event
+# 3. Create your first event
 partiful events create --title "Game Night" --date "Apr 15 7pm" --location "My Place"
 
-# List guests
+# 4. List your events
+partiful events list
+
+# 5. Invite and blast (use an eventId from step 4)
 partiful guests list <eventId>
+partiful blasts send <eventId> --message "See you tonight!"
+```
 
-# Clone an event to next week
-partiful +clone <eventId>
+## Commands
 
-# Export event + guests
-partiful +export <eventId> --format json --output event.json
+### `auth` — Manage authentication
 
-# Share link
-partiful +share <eventId>
+```bash
+partiful auth login +12065551234    # SMS-based auth
+partiful auth status                # Check current auth
+partiful auth logout                # Clear credentials
 ```
 
-## Command Reference
+### `events` — Manage events
 
-### Global Options
-
-| Option | Description |
-|--------|-------------|
-| `--format <fmt>` | Output format: `json` (default), `table`, `csv`, `ndjson` |
-| `--dry-run` | Preview request without executing |
-| `-y, --yes` | Skip confirmation prompts |
-| `--force` | Skip confirmation and overwrite protection |
-| `-v, --verbose` | Show request details on stderr |
-| `-o, --output <path>` | Write output to file |
-| `--no-color` | Disable colored output |
+```bash
+partiful events list                # Upcoming events
+partiful events list --past         # Past events
+partiful events get <id>            # Event details
+partiful events create --title "Party" --date "May 1 8pm" --location "Rooftop"
+partiful events update <id> --title "New Title"
+partiful events cancel <id>
+```
 
-### Commands
+### `guests` — Manage event guests
 
-#### `auth` — Manage authentication
+```bash
+partiful guests list <eventId>      # All guests with RSVP status
+partiful guests invite <eventId>    # Send invites
+```
 
-| Subcommand | Description |
-|------------|-------------|
-| `auth save` | Save auth credentials (`--token`, `--refresh`, `--user-id`) |
-| `auth status` | Check current auth status |
-| `auth refresh` | Force token refresh |
-| `auth clear` | Remove saved credentials |
+### `blasts` — Text guests
 
-#### `events` — Manage events
+```bash
+partiful blasts send <eventId> --message "Doors open at 7!"
+```
 
-| Subcommand | Description |
-|------------|-------------|
-| `events list` | List upcoming events (`--past` for past events) |
-| `events get <id>` | Get event details |
-| `events create` | Create a new event (`--title`, `--date`, `--location`, etc.) |
-| `events update <id>` | Update event via Firestore (`--title`, `--date`, etc.) |
-| `events cancel <id>` | Cancel an event |
+### `contacts` — Manage contacts
 
-#### `guests` — Manage event guests
+```bash
+partiful contacts list              # All contacts
+partiful contacts list "alex"       # Search by name
+```
 
-| Subcommand | Description |
-|------------|-------------|
-| `guests list <eventId>` | List guests with RSVP status |
-| `guests summary <eventId>` | Guest count summary by status |
+### `cohosts` — Manage co-hosts
 
-#### `contacts` — Manage contacts
+```bash
+partiful cohosts list <eventId>
+partiful cohosts add <eventId> --name "Alex" --name "Jordan"
+partiful cohosts remove <eventId>
+```
 
-| Subcommand | Description |
-|------------|-------------|
-| `contacts list` | List your Partiful contacts |
+### `posters` — Browse poster catalog
 
-#### `blasts` — Text blasts to event guests
+```bash
+partiful posters list
+partiful posters search "birthday"
+partiful posters get <posterId>
+```
 
-| Subcommand | Description |
-|------------|-------------|
-| `blasts send <eventId>` | Send a text blast (`--message`, `--filter`) |
-| `blasts history <eventId>` | View blast history |
+### `template` — Event templates
 
-### Helper Commands
+```bash
+partiful template list                          # List saved templates
+partiful template show <name>                   # Show template details
+partiful template save --name "Game Night"       # Save a template
+partiful template edit <name>                   # Edit a template
+partiful template delete <name>                 # Delete a template
+```
 
-Helpers use the `+` prefix to distinguish from core CRUD commands.
+### `bulk` — Batch operations
 
-| Command | Description |
-|---------|-------------|
-| `+clone <eventId>` | Clone an event with shifted date (`--title`, `--date`, `--shift <days>`) |
-| `+watch <eventId>` | Poll for guest RSVP changes as NDJSON (`--interval <s>`, `--duration <m>`) |
-| `+export <eventId>` | Export event + guests to file (`--format json\|csv`, `--output <path>`) |
-| `+share <eventId>` | Generate shareable event link |
+```bash
+partiful bulk create events.json                              # Create from JSON file
+partiful bulk update --filter "title contains Game" --location "New Spot"  # Bulk update
+```
 
-#### `+clone` Examples
+### `schema` — Introspect command parameters
 
 ```bash
-# Clone to next week (default: +7 days)
-partiful +clone FDwyIXK42phoWEZgFin5
+partiful schema events.create       # Show params for events create
+```
 
-# Clone with specific date
-partiful +clone FDwyIXK42phoWEZgFin5 --date "May 1 8pm"
+### `doctor` — Health check
 
-# Clone with new title
-partiful +clone FDwyIXK42phoWEZgFin5 --title "Game Night v2" --shift 14
+```bash
+partiful doctor                     # Check auth, connectivity, setup
 ```
 
-#### `+watch` Example
+### Helper commands
+
+Helpers use the `+` prefix:
 
 ```bash
-# Watch for 30 minutes, polling every 15 seconds
-partiful +watch FDwyIXK42phoWEZgFin5 --interval 15 --duration 30
-```
+# Clone an event to next week
+partiful +clone <eventId>
+partiful +clone <eventId> --date "May 1 8pm" --title "Game Night v2"
 
-Output (NDJSON):
-```json
-{"type":"rsvp_change","guest":{"name":"Alex","count":1},"from":"SENT","to":"GOING","timestamp":"..."}
-{"type":"new_guest","guest":{"name":"Jordan","count":2},"from":null,"to":"GOING","timestamp":"..."}
+# Watch RSVPs in real-time (NDJSON stream)
+partiful +watch <eventId> --interval 15 --duration 30
+
+# Export event + guest list
+partiful +export <eventId> --format json --output party.json
+partiful +export <eventId> --format csv
+
+# Get shareable link
+partiful +share <eventId>
 ```
 
-#### `+export` Example
+## Global Flags
 
-```bash
-# Export as JSON
-partiful +export FDwyIXK42phoWEZgFin5 --output party.json
+`--format <fmt>` (json/table/csv/ndjson) · `--dry-run` · `-y, --yes` · `--force` · `-v, --verbose` · `-o, --output <path>` · `--no-color`
+
+## Auth Setup
+
+Partiful doesn't have a public API. This CLI authenticates via SMS verification through Firebase.
 
-# Export guest list as CSV
-partiful +export FDwyIXK42phoWEZgFin5 --format csv
+```bash
+partiful auth login +12065551234   # sends SMS code, completes auth
+partiful auth status               # verify you're logged in
 ```
 
-## JSON Envelope Format
+Tokens auto-refresh when expired. Run `partiful doctor` if anything seems off.
 
-All JSON output follows a consistent envelope:
+## JSON Output
 
-### Success
+All commands support `--format json`. Responses follow a consistent envelope:
 
 ```json
 {
@@ -175,33 +194,13 @@ All JSON output follows a consistent envelope:
 }
 ```
 
-### Error
-
-```json
-{
-  "status": "error",
-  "error": {
-    "code": 1,
-    "type": "api_error",
-    "message": "Description of what went wrong"
-  }
-}
-```
-
-## Exit Codes
+Errors return `{ "status": "error", "error": { "code": 1, "type": "api_error", "message": "..." } }`.
 
-| Code | Meaning |
-|------|---------|
-| `0` | Success |
-| `1` | API error |
-| `2` | Authentication error |
-| `3` | Validation error |
-| `4` | Not found |
-| `5` | Internal error |
+Exit codes: `0` success · `1` API error · `2` auth error · `3` validation · `4` not found · `5` internal.
 
 ## Contributing
 
-See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, testing, and contribution guidelines.
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and guidelines.
 
 ## License