petdex 1.3.1 → 1.4.0

package/AGENTS.md

@@ -1,6 +1,6 @@
 # petdex - Agent Guide
 
-`petdex` is the catalog CLI for [Petdex](https://petdex.dev): browse, install, submit, and edit animated pixel-art pets (mascots) for coding agents, from the terminal. It installs pets into `~/.petdex/pets/` and `~/.codex/pets/`, and submits new pets to the gallery. The floating mascot itself ships as the separate **Petdex Desktop app** (petdex.dev/download), which installs agent hooks from its own Settings window and updates itself; this CLI is the catalog client. Reach for it when a user wants to install a pet, publish a pet they created, or edit one they own.
+`petdex` is the catalog CLI for [Petdex](https://petdex.dev): browse, install, submit, edit, and organize animated pixel-art pets (mascots) for coding agents, from the terminal. It installs pets into `~/.petdex/pets/` and `~/.codex/pets/`, submits new pets to the gallery, and manages personal collections of approved pets. The floating mascot itself ships as the separate **Petdex Desktop app** (petdex.dev/download), which installs agent hooks from its own Settings window and updates itself; this CLI is the catalog client. Reach for it when a user wants to install a pet, publish a pet they created, edit one they own, or group their approved pets.
 
 ## Install
 
@@ -25,6 +25,10 @@ The published name is plain `petdex` (unscoped, no `@crafter/` prefix). Requires
 | `petdex whoami` | Show signed-in user |
 | `petdex submit <path> [--force]` | Submit a pet folder, zip, or parent folder of pets (bulk) |
 | `petdex edit <slug>` | Edit a pet you own: `--desc "..."`, `--displayName "..."`, `--sprite <file>`, `--meta <pet.json>`, `--zip <file>` |
+| `petdex collection list` | List your collections (`--json` for machine output) |
+| `petdex collection create` | Create a collection with `--title`, `--desc`, `--pets`, `--cover`, `--external-url`, or `--all-approved` |
+| `petdex collection edit <id-or-slug>` | Partially update a personal collection; omitted fields are preserved |
+| `petdex collection delete <id-or-slug> --yes` | Delete a personal collection after explicit confirmation |
 | `petdex telemetry [on\|off\|status]` | Manage anonymous usage telemetry |
 | `petdex version` (or `--version`, `-v`) | Print the CLI version |
 
@@ -49,7 +53,13 @@ Removed in v1.0.0: `init`, `up`, `down`, `toggle`, `desktop`, `update`, `doctor`
    ```bash
    petdex edit boba --desc "A tiny otter sipping bubble tea" --sprite ./new.webp
    ```
-4. Check identity / sign out:
+4. Organize approved pets into a collection:
+   ```bash
+   petdex collection create --title "Desk crew" --pets boba,mochi --cover boba
+   petdex collection list   # the new collection's slug is generated; copy it here
+   petdex collection edit <slug> --desc "Small companions for focused work"
+   ```
+5. Check identity / sign out:
    ```bash
    petdex whoami
    petdex logout
@@ -63,6 +73,7 @@ Removed in v1.0.0: `init`, `up`, `down`, `toggle`, `desktop`, `update`, `doctor`
 | Get a pet onto this machine | `petdex install <slug>` (deduped, multiple slugs OK) |
 | Publish/share a pet | `petdex login`, then `petdex submit <path>` |
 | Update a published pet's text or sprite | `petdex edit <slug> [flags]` |
+| Group approved pets | `petdex collection create|edit|delete ...` |
 | Show/hide the mascot, wire agent hooks, diagnose | Not this CLI: use the Petdex Desktop app (petdex.dev/download); its Settings installs hooks per agent |
 | Choose the active mascot | Petdex Desktop Settings (hover the pet, Cmd+,) |
 | Create a brand-new pet | Not this CLI: type `/pet` in the ChatGPT desktop app, then `petdex submit` the export |
@@ -74,5 +85,6 @@ Removed in v1.0.0: `init`, `up`, `down`, `toggle`, `desktop`, `update`, `doctor`
 - Wrong: `petdex init` / `petdex doctor` / `petdex hooks install` / `petdex select` from pre-1.0 docs. Those commands were removed in v1.0.0; mascot lifecycle and hooks live in the Petdex Desktop app.
 - Wrong: running on Node < 20 (npm engine error). Correct: upgrade Node (`nvm install 20`).
 - Wrong: `petdex submit` in a headless/CI session without prior auth. `petdex login` needs a browser for the OAuth callback; sign in interactively first (tokens persist in the OS keychain, service `petdex-cli`).
+- Collection commands require login and allow at most 10 personal collections per account. The 24-pet limit bounds growth rather than the stored row, so a collection created before it existed can still be renamed or shrunk, but not grown. Use comma-separated slugs with `--pets`; `--all-approved` on `create` fails when more than 24 pets are approved, and deletion requires `--yes`. `--cover` must name a member of the collection; pass `--cover ""` to clear the cover (an omitted `--cover` leaves it alone).
 - Wrong: submitting a folder without `pet.json` + `spritesheet.webp` (or `.png`) at its root, or a sprite that is not an 8x9 grid (1536x1872) or v2 8x11 grid (1536x2288, the ChatGPT export shape), or a clean scale of either. The register step rejects it (`invalid_spritesheet`).
 - Note: submissions are rate-limited to 10 per 24h per user. Slugs auto-deduplicate on collision (`boba` -> `boba-2`). Point at non-production deployments with `PETDEX_URL`, and `CLERK_ISSUER` + `CLERK_OAUTH_CLIENT_ID` together.

package/CLAUDE.md

@@ -1,5 +1,5 @@
 # petdex
 
-Catalog CLI for Petdex: browse, install, submit, and edit animated pixel-art mascots for coding agents (`npx -y petdex install <slug>`); the mascot itself runs in the Petdex Desktop app.
+Catalog CLI for Petdex: browse, install, submit, edit, and organize animated pixel-art mascots for coding agents (`npx -y petdex install <slug>`); the mascot itself runs in the Petdex Desktop app.
 
 See AGENTS.md for complete usage documentation for this package.

package/README.md

@@ -31,6 +31,8 @@ petdex submit ~/.petdex/pets/boba   # share a single pet
 petdex submit ~/.petdex/pets        # bulk submit every subfolder
 petdex whoami                      # confirm signed-in identity
 petdex logout                      # clear stored credentials
+petdex collection list             # list your collections
+petdex collection create --title "My pets" --pets boba,mochi
 ```
 
 After installing a pet, pick the active mascot in Petdex Desktop: hover the pet and
@@ -53,9 +55,46 @@ The `init`, `up`, `down`, `toggle`, `desktop`, `update`, `doctor`, and `hooks` c
 | `petdex install <slug>` | Install a pet into `~/.petdex/pets/<slug>/` and `~/.codex/pets/<slug>/`. |
 | `petdex submit <path>` | Submit a pet folder, zip, or parent of pets (bulk). |
 | `petdex edit <slug>` | Edit a pet you own (`--desc`, `--displayName`, `--sprite`, `--meta`, `--zip`). |
+| `petdex collection list` | List your collections (`--json` for machine output). |
+| `petdex collection create` | Create a personal collection (`--title`, `--desc`, `--pets`, `--cover`, `--external-url`, `--all-approved`). |
+| `petdex collection edit <id-or-slug>` | Partially update a personal collection. The reference can be the collection id or slug. |
+| `petdex collection delete <id-or-slug>` | Delete a personal collection; requires `--yes`. |
 | `petdex telemetry [on\|off\|status]` | Manage anonymous usage telemetry. |
 | `petdex --version` | Print the CLI version. |
 
+## Collection management
+
+Collections group approved pets on your profile. All collection commands
+require `petdex login` first, and all support `--json` for machine-readable
+output.
+
+```sh
+petdex collection list --json
+petdex collection create --title "My pets" --pets boba,mochi --cover boba
+petdex collection list                       # copy the slug from here
+petdex collection edit <slug> --desc "A small desk crew" --external-url https://example.com
+petdex collection edit <slug> --all-approved
+petdex collection delete <slug> --yes
+```
+
+`collection edit` and `collection delete` take either the collection id or its
+slug. New collections get a generated slug (`collection-<32 hex chars>`);
+there is no flag to set one, so read it from `petdex collection list` first.
+
+`--pets` takes a comma-separated list of pet slugs. `collection edit` accepts
+any subset of the update flags, so omitted fields are preserved. `--all-approved`
+selects every approved pet owned by you; on `create`, use it only when that set
+has 24 or fewer pets. If you pass both `--all-approved` and `--pets`, `--all-approved`
+wins and the explicit list is ignored. Each account can have up to 10 personal
+collections, and `--cover` must name a pet in the collection — with an explicit
+`--pets`, that means the cover has to appear in the list. Pass `--cover ""` to
+clear the cover; with no `--pets` the collection keeps its members and shows
+none as the cover. `--external-url`
+accepts safe HTTPS links only. The 24-pet limit bounds growth: a collection that
+already exceeds it — one created before the limit existed — can still be renamed
+or shrunk, but not grown. An empty member list is refused, because it would
+remove every member; delete the collection instead.
+
 ## How `submit` works
 
 The CLI accepts three input shapes: