@esthernandez/vibe-cartographer 1.0.0 → 1.0.1

package/CHANGELOG.md

@@ -9,6 +9,17 @@ All notable changes to this project are documented here. The format follows [Kee
 
 - Nothing yet.
 
+## [1.0.1] — 2026-04-15 — Install docs
+
+### Changed
+
+- **README and INSTALL rewritten** to document all three Claude Desktop install paths: **Add marketplace** (recommended — pulls from GitHub via `.claude-plugin/marketplace.json`), **npm install -g** (for Claude Code CLI / VS Code / JetBrains), and **Upload plugin** (for local iteration via `python scripts/build-plugin.py`).
+- Added a **"Which option should I use?"** decision table mapping situation → recommended install path.
+- Added a reproducible `scripts/build-plugin.py` build script that produces a `.plugin` bundle in `bundles/` for the upload-plugin path. Excludes `dist/`, `node_modules/`, `src/`, and other runtime/build artifacts per Cowork's plugin spec.
+- GitHub releases now ship a pre-built `.plugin` file as a release asset for one-click downloads.
+
+No behavior changes — this release exists so the npm-published README on `npmjs.com/package/@esthernandez/vibe-cartographer` reflects the marketplace install path.
+
 ## [1.0.0] — 2026-04-15 — Rebrand to Vibe Cartographer
 
 The plugin formerly known as `@esthernandez/app-project-readiness` is now **Vibe Cartographer**. Same 8-command spec-driven workflow, same personas, same session memory — new name that actually says what the plugin does: *plot your course from idea to shipped app*.

package/INSTALL.md

@@ -8,42 +8,69 @@
 
 ## Install paths
 
-You only need one of these. Pick whichever matches how you're already running Claude Code.
+Pick whichever matches how you're running Claude Code. All three lead to the same plugin working.
 
-### Option 1: npm (recommended)
+### Option 1: Claude Desktop — Add marketplace (recommended)
+
+The cleanest path. Pulls from GitHub directly, supports `Sync` to update, no file downloads.
+
+1. Open Claude Desktop → **Personal plugins** panel (left sidebar)
+2. Click the **+** button → **Add marketplace**
+3. Enter: `estevanhernandez-stack-ed/vibe-cartographer`
+4. Click **Sync**
+
+Claude Desktop reads `.claude-plugin/marketplace.json` at the repo root, discovers the `vibe-cartographer` plugin inside `./plugins/vibe-cartographer`, and registers its slash commands. Updates propagate by clicking **Sync** again on the marketplace entry.
+
+### Option 2: Claude Code CLI — npm
+
+For users running Claude Code in a terminal, VS Code, or JetBrains.
 
 ```bash
 npm install -g @esthernandez/vibe-cartographer
 ```
 
-This drops the plugin files on your disk at your npm global root — typically `~/.npm-global/lib/node_modules/@esthernandez/vibe-cartographer/` on macOS/Linux or `%APPDATA%\npm\node_modules\@esthernandez\vibe-cartographer\` on Windows. You then need to tell Claude Code about them — see [Connecting to Claude Code](#connecting-to-claude-code) below.
+This drops the plugin files at:
 
-### Option 2: Claude Desktop — Personal plugin
+- **macOS/Linux:** `~/.npm-global/lib/node_modules/@esthernandez/vibe-cartographer/plugins/vibe-cartographer/`
+- **Windows:** `%APPDATA%\npm\node_modules\@esthernandez\vibe-cartographer\plugins\vibe-cartographer\`
 
-If you're on the Claude Desktop app and don't want an npm install:
+If your Claude Code CLI has a `plugin add <path>` command, point it at that path. Otherwise, use Option 1 (Add marketplace) — it works for CLI clients too because Claude Code reads marketplace entries from the global plugin config.
 
-1. Open **Personal plugins** in Claude Desktop (the panel in the left sidebar).
-2. Click the **+** button → **Create plugin**.
-3. Point it at a local clone of this repo (see Option 3 for the clone step).
-4. The plugin's slash commands become available immediately — no restart required.
+### Option 3: Claude Desktop — Upload plugin (for local iteration)
 
-### Option 3: Clone and reference locally
+For testing changes locally before pushing them to GitHub.
 
-```bash
-git clone https://github.com/estevanhernandez-stack-ed/vibe-cartographer ~/vibe-cartographer
-```
+1. Clone the repo:
+
+   ```bash
+   git clone https://github.com/estevanhernandez-stack-ed/vibe-cartographer
+   cd vibe-cartographer
+   ```
+
+2. Build a `.plugin` bundle:
+
+   ```bash
+   python scripts/build-plugin.py
+   ```
+
+   This writes `bundles/vibe-cartographer-<version>.plugin` — a zip archive Cowork accepts directly. The script excludes `dist/`, `node_modules/`, `src/`, and other runtime/build artifacts per Cowork's plugin spec.
+
+3. In Claude Desktop → **Personal plugins** → **+** → **Upload plugin**, pick the `.plugin` file.
 
-Then point Claude Code at `~/vibe-cartographer/plugins/vibe-cartographer/` as the plugin root. This is the same as Option 2 minus the Claude Desktop UI step — useful if you're on the Claude Code CLI directly.
+You can also download a pre-built `.plugin` file from the [GitHub releases page](https://github.com/estevanhernandez-stack-ed/vibe-cartographer/releases) — each tagged release ships a ready-to-upload asset.
 
-## Connecting to Claude Code
+## Which option should I use?
 
-After installing, Claude Code needs to know where the plugin lives. The exact steps depend on your client:
+| Situation                                            | Option                                                                            |
+| ---------------------------------------------------- | --------------------------------------------------------------------------------- |
+| I use Claude Desktop and want the simplest install   | **Option 1** (Add marketplace)                                                    |
+| I use Claude Code CLI / VS Code / JetBrains          | **Option 2** (npm) — then use Option 1 in Claude Desktop if you also use it there |
+| I'm developing or testing plugin changes locally     | **Option 3** (Upload plugin)                                                      |
+| I want to install without an internet connection     | **Option 3** — download the `.plugin` from releases ahead of time                 |
 
-- **Claude Desktop** — use the **Personal plugins** panel (**+** button → **Create plugin** → point at the folder). Same flow for Option 1 (point at the npm install path) and Option 3 (point at your local clone).
-- **Claude Code CLI** — if your version has a plugin-add command, point it at the install path. Otherwise clone the repo and rely on Claude Code's plugin discovery for folders in its known marketplace list.
-- **VS Code / JetBrains** — Claude Code in your IDE reads from the same global plugin config as Claude Desktop. Install via Option 2 on Claude Desktop first and the IDE will pick it up on next launch.
+## Verifying the install
 
-**Pointing at the right folder matters.** The plugin root is the folder that contains `.claude-plugin/plugin.json` — in this repo that's `plugins/vibe-cartographer/`, not the repo root. Pointing at the repo root will not work.
+**The plugin root is the folder that contains `.claude-plugin/plugin.json`.** In this repo that's `plugins/vibe-cartographer/`, not the repo root. Most install paths handle this automatically (marketplace manifest tells Claude Desktop where to look), but if you're troubleshooting, that's the folder to point at.
 
 ## Verification
 

package/README.md

@@ -54,40 +54,50 @@ See [`plugins/vibe-cartographer/architecture/`](plugins/vibe-cartographer/archit
 
 ## Install
 
-Requires [Claude Code](https://claude.ai/code) or Claude Desktop with plugin support.
+Requires [Claude Code](https://claude.ai/code) CLI or Claude Desktop with plugin support. Pick whichever path matches how you're running Claude Code — all three lead to the same plugin working inside a fresh project folder.
 
-### Option 1: npm (recommended)
+### Option 1: Claude Desktop — Add marketplace (recommended)
+
+The cleanest install. Pulls straight from GitHub, no file download, supports `Sync` to update.
+
+1. Open Claude Desktop → **Personal plugins** panel
+2. Click the **+** button → **Add marketplace**
+3. Enter: `estevanhernandez-stack-ed/vibe-cartographer`
+4. Click **Sync**
+
+Claude Desktop reads `.claude-plugin/marketplace.json` at the repo root, loads the `vibe-cartographer` plugin from inside `./plugins/vibe-cartographer`, and the slash commands (`/onboard`, `/scope`, `/prd`, etc.) become available.
+
+### Option 2: Claude Code CLI — npm
 
 ```bash
 npm install -g @esthernandez/vibe-cartographer
 ```
 
-Then in Claude Code / Claude Desktop, point your personal plugins at the installed path:
+The package ships the plugin files at `<npm-global>/node_modules/@esthernandez/vibe-cartographer/plugins/vibe-cartographer/`. If your Claude Code CLI has a plugin-add command, point it at that path; otherwise use Option 1 (Add marketplace) and the marketplace manifest will do the discovery for you.
 
-- macOS/Linux: `~/.npm-global/lib/node_modules/@esthernandez/vibe-cartographer/plugins/vibe-cartographer`
-- Windows: `%APPDATA%\npm\node_modules\@esthernandez\vibe-cartographer\plugins\vibe-cartographer`
+### Option 3: Claude Desktop — Upload plugin
 
-### Option 2: Claude Desktop personal plugin
+For local iteration before you push changes to GitHub.
 
-1. Open Claude Desktop's **Personal plugins** panel.
-2. Click **+ Create a plugin**.
-3. Point it to the `plugins/vibe-cartographer` folder from this repo (cloned or downloaded).
-4. The slash commands (`/onboard`, `/scope`, `/prd`, etc.) become available.
+1. Clone the repo: `git clone https://github.com/estevanhernandez-stack-ed/vibe-cartographer`
+2. Build a `.plugin` bundle:
 
-### Option 3: Clone and reference locally
+   ```bash
+   python scripts/build-plugin.py
+   ```
 
-```bash
-git clone https://github.com/estevanhernandez-stack-ed/vibe-cartographer ~/vibe-cartographer
-```
+   This writes `bundles/vibe-cartographer-<version>.plugin` — a zip archive Cowork accepts directly.
+3. In Claude Desktop → **Personal plugins** → **+** → **Upload plugin**, pick the `.plugin` file.
 
-Then point your Claude Code / Claude Desktop at `~/vibe-cartographer/plugins/vibe-cartographer`.
+Also available as a one-click download from the [GitHub releases page](https://github.com/estevanhernandez-stack-ed/vibe-cartographer/releases) — each release ships a pre-built `.plugin` file as a release asset.
 
 ### Migrating from `@esthernandez/app-project-readiness`
 
-Vibe Cartographer is the rename of what was previously `@esthernandez/app-project-readiness` (v0.5.0 and earlier). The migration is automatic:
+Vibe Cartographer is the rename of what was previously `@esthernandez/app-project-readiness` (v0.5.0 and earlier). Migration is automatic on first `/onboard` run:
 
-- Your unified builder profile at `~/.claude/profiles/builder.json` gets its `plugins.app-project-readiness` block copied to `plugins.vibe-cartographer` on first v1.0.0+ run.
-- The old `@esthernandez/app-project-readiness` npm package is deprecated. Run `npm install -g @esthernandez/vibe-cartographer` and uninstall the old one when you're ready.
+- Your unified builder profile at `~/.claude/profiles/builder.json` gets its `plugins.app-project-readiness` block copied to `plugins.vibe-cartographer` (old key preserved for one release as a safety net).
+- Deep-legacy markdown profiles at `~/.claude/plugins/data/app-project-readiness/user-profile.md` also migrate.
+- The old `@esthernandez/app-project-readiness` npm package is deprecated with a pointer. Run `npm install -g @esthernandez/vibe-cartographer` and uninstall the old one when you're ready.
 - Legacy session logs at `~/.claude/plugins/data/app-project-readiness/sessions/` are left in place — append-only history isn't touched.
 
 ### Start the workflow

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@esthernandez/vibe-cartographer",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Vibe Cartographer — plot your course from idea to shipped app. Spec-driven development workflow as a Claude Code plugin, delivered as eight slash commands (onboard, scope, prd, spec, checklist, build, iterate, reflect).",
   "author": "626Labs LLC",
   "license": "MIT",

package/plugins/vibe-cartographer/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "vibe-cartographer",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Vibe Cartographer — plot your course from idea to shipped app. Spec-driven development delivered as eight slash commands: onboard, scope, prd, spec, checklist, build, iterate, reflect.",
   "author": {"name": "626Labs LLC"}
 }