improve readme

Author: Cesar-M-Diaz

README.md

@@ -89,25 +89,37 @@ On setup:
 
 The GitHub marketplace flow installs from the repository root.
 
+The setup step requires the `nsolid-plugin` CLI on your PATH:
+
+```bash
+npm i -g nsolid-plugin          # stable release
+# during pre-release:
+npm i -g nsolid-plugin@next
+```
+
+Or invoke it once-off with `npx -y nsolid-plugin setup --harness <harness>` (`npx -y nsolid-plugin@next ...` during pre-release).
+
 ### Claude Code
 
 ```bash
 claude plugin marketplace add NodeSource/nsolid-plugin
 claude plugin install nsolid-plugin@nodesource
-npx -y @nodesource/nsolid-plugin setup --harness claude
+nsolid-plugin setup --harness claude
 ```
 
 Claude installs plugins through marketplaces. The repository root includes `.claude-plugin/marketplace.json`, so GitHub install works directly. If marketplace/local plugin install is unavailable, `nsolid-plugin install --harness claude` is the fallback direct installer and does not open a browser.
 
+> `nsolid-plugin` must be available on your PATH. Once published, install it globally (`npm i -g nsolid-plugin`) or invoke it via npx (`npx -y nsolid-plugin setup --harness claude`). During the pre-release window, use the prerelease tag (`npx -y nsolid-plugin@next ...` or `npm i -g nsolid-plugin@next`).
+
 ### Codex CLI
 
 ```bash
 codex plugin marketplace add NodeSource/nsolid-plugin
 codex plugin add nsolid-plugin@nodesource
-npx -y @nodesource/nsolid-plugin setup --harness codex
+nsolid-plugin setup --harness codex
 ```
 
-Codex is marketplace-owned. A NodeSource-owned Git/local marketplace can be used as fallback if OpenAI curation is unavailable. Authentication remains explicit through `npx -y @nodesource/nsolid-plugin setup --harness codex`.
+Codex is marketplace-owned. A NodeSource-owned Git/local marketplace can be used as fallback if OpenAI curation is unavailable. Authentication remains explicit through `nsolid-plugin setup --harness codex` (or `npx -y nsolid-plugin setup --harness codex`).
 
 ### OpenCode
 
@@ -123,7 +135,7 @@ Use `nsolid-plugin install --harness opencode` only as a no-browser fallback/rep
 
 ```bash
 agy plugin install https://github.com/NodeSource/nsolid-plugin.git
-npx -y @nodesource/nsolid-plugin setup --harness antigravity
+nsolid-plugin setup --harness antigravity
 ```
 
 Antigravity installs the repository root as a native plugin and stages skills/MCP wrappers under `~/.gemini/antigravity-cli/plugins/nsolid-plugin/`. Install does not start auth.

docs/qa-guide.md

@@ -52,12 +52,14 @@ Refresh the committed root manifests from `bundle.json` before native-install QA
 pnpm plugin:root
 ```
 
-`plugin:root` runs `scripts/materialize-github-marketplace.mjs`, which rewrites the root manifests and validates that every bundle skill exists at `skills/<name>/SKILL.md`. Leave the resulting files staged for QA; native install (sections 7–9) reads them directly from the repo root. To verify the committed manifests are in sync (no drift after a `bundle.json` change), run `pnpm plugin:root:check`.
+`plugin:root` runs `scripts/materialize-github-marketplace.mjs`, which rewrites the root manifests and validates that every bundle skill exists at `skills/<name>/SKILL.md`. Leave the resulting files staged for QA; native install (sections 8–10) reads them directly from the repo root. To verify the committed manifests are in sync (no drift after a `bundle.json` change), run `pnpm plugin:root:check`.
 
 ## 3. Real HOME CLI QA setup
 
 This QA flow uses your real HOME and modifies real harness configs.
 
+Local build (default — QA the code in this checkout):
+
 ```bash
 export REPO_ROOT="$(pwd)"
 export REAL_HOME="$(node -e 'console.log(require("node:os").homedir())')"
@@ -66,6 +68,18 @@ export CLI="node $REPO_ROOT/packages/core/dist/src/cli.js"
 echo "Using real HOME: $HOME"
 ```
 
+Published package (once `nsolid-plugin` is on npm — QA the shipped artifact instead):
+
+```bash
+export REAL_HOME="$(node -e 'console.log(require("node:os").homedir())')"
+export HOME="$REAL_HOME"
+# stable release:
+export CLI="npx -y nsolid-plugin"
+# prerelease (published under the next dist-tag):
+export CLI="npx -y nsolid-plugin@next"
+echo "Using real HOME: $HOME"
+```
+
 Confirm CLI help:
 
 ```bash
@@ -163,7 +177,38 @@ Expected:
 - `uninstall` removes fallback OpenCode artifacts.
 - `logout` removes credentials or says none were found.
 
-## 7. Claude Code native install QA
+## 7. Published CLI package QA
+
+Once `nsolid-plugin` is published to npm, QA the shipped package itself — not the local build — to confirm the `bin` works, the right files ship, and skills/bundle are included. Run this in a throwaway directory.
+
+```bash
+# In a throwaway dir, NOT the repo:
+mkdir -p /tmp/nsolid-pkg-qa && cd /tmp/nsolid-pkg-qa
+
+# stable release:
+npx -y nsolid-plugin --help
+# prerelease:
+npx -y nsolid-plugin@next --help
+
+# Inspect what the package actually ships (files included in the tarball):
+npm pack nsolid-plugin@next --dry-run 2>&1 | sed -n '/Tarball Contents/,/Tarball Details/p'
+```
+
+Expected:
+- `--help` runs without a local build; the `nsolid-plugin` bin is executable.
+- Tarball contents include `dist/src/`, `skills/`, `bundle.json`, and `scripts/`.
+- The `bin` entry resolves to `./dist/src/cli.js` and that file is executable.
+- No `test/`, no source `*.ts`, no `tsconfig` shipped.
+
+Optional — run `doctor` from the published package against a real HOME:
+
+```bash
+export REAL_HOME="$(node -e 'console.log(require("node:os").homedir())')"
+export HOME="$REAL_HOME"
+npx -y nsolid-plugin@next doctor --harness claude || true
+```
+
+## 8. Claude Code native install QA
 
 Claude installs from the GitHub plugin root. The local path can be the repo checkout itself, or a clone for closer-to-release coverage.
 
@@ -212,7 +257,7 @@ claude plugin marketplace remove nodesource || true
 $CLI uninstall --harness claude --keep-credentials || true
 ```
 
-## 8. Codex native install QA
+## 9. Codex native install QA
 
 Codex installs from the GitHub plugin root. The marketplace name is `nodesource`.
 
@@ -265,7 +310,7 @@ $CLI uninstall --harness codex --keep-credentials || true
 
 If `codex plugin remove nsolid-plugin@nodesource` is unavailable, remove it through `codex /plugins`.
 
-## 9. Antigravity native install QA
+## 10. Antigravity native install QA
 
 Antigravity installs directly from the GitHub plugin root (a git URL).
 
@@ -318,7 +363,7 @@ agy plugin uninstall nsolid-plugin || true
 $CLI uninstall --harness antigravity --keep-credentials || true
 ```
 
-## 10. Pi package install QA
+## 11. Pi package install QA
 
 Local pre-release package QA with production accounts:
 
@@ -352,7 +397,10 @@ Production package QA uses the published Pi package instead of the local package
 export HOME="$REAL_HOME"
 $CLI uninstall --harness pi --keep-credentials || true
 find "$HOME/.pi/agent/skills" "$HOME/.agents/skills" -maxdepth 1 -name 'ns-*' -exec rm -rf {} + 2>/dev/null || true
+# stable release:
 pi install npm:nsolid-pi-plugin
+# prerelease (published under the next dist-tag) — pin the exact version, e.g.:
+# pi install npm:nsolid-pi-plugin@1.0.0-next.0
 $CLI setup --harness pi --yes
 pi install npm:pi-mcp-adapter
 $CLI doctor --harness pi || true
@@ -381,7 +429,7 @@ $CLI uninstall --harness pi --keep-credentials || true
 pnpm plugin:clean
 ```
 
-## 11. OpenCode CLI-only install QA
+## 12. OpenCode CLI-only install QA
 
 OpenCode is CLI-only. `setup --harness opencode` is the primary onboarding command because it authenticates and then performs the direct install; `install --harness opencode` is a no-browser fallback/repair path.
 
@@ -415,7 +463,7 @@ Cleanup:
 $CLI uninstall --harness opencode --keep-credentials || true
 ```
 
-## 12. Final cleanup
+## 13. Final cleanup
 
 ```bash
 $CLI logout || true

packages/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nsolid-plugin",
-  "version": "0.1.0",
+  "version": "1.0.0-next.0",
   "type": "module",
   "main": "dist/src/index.js",
   "types": "dist/src/index.d.ts",

packages/pi-plugin/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nsolid-pi-plugin",
-  "version": "0.1.0",
+  "version": "1.0.0-next.0",
   "type": "module",
   "description": "N|Solid Plugin for Pi Agent",
   "keywords": [