docs: clarify publish policy and cobra CLI UX

Author: Nomadcxx

docs/PUBLISHING.md

@@ -10,7 +10,10 @@ This project is publishable as the npm package `@rama_nigg/open-cursor`. The bin
 
 ## Release Checklist
 
-1. Update version in `package.json` (semver).
+1. Decide if this is a publish-worthy change.
+   - Docs-only or refactors with no user-visible behavior change: do not publish.
+   - User-visible changes (plugin behavior, installer behavior, CLI behavior): publish.
+2. Update version in `package.json` (semver) only when publishing.
 2. Build and run tests locally:
    - `bun install`
    - `bun run build`
@@ -37,3 +40,9 @@ Publish step:
 - `npm publish --access public`
 
 If you need a non-publish validation run, execute the same build/test steps locally and use `npm pack --dry-run`.
+
+## Dist Tags (Optional)
+
+Use dist-tags for pre-releases instead of publishing a rapid stream of patch versions:
+- `latest`: stable releases
+- `beta`: pre-release channel (for example `2.2.0-beta.1`)

docs/implementation/open-cursor-go-cli-cobra.md

@@ -25,9 +25,11 @@ Reference implementation style: `/home/nomadx/Documents/jellywatch/cmd/jellywatc
 Binary name: `open-cursor`
 
 Commands:
-- `open-cursor install`
+- `open-cursor install` (idempotent)
+  - Configure OpenCode for Cursor in one step. This is safe to re-run any time.
   - Ensure plugin file exists: `~/.config/opencode/plugin/cursor-acp.js` (or XDG equivalent)
   - Ensure provider config exists/merged in `opencode.json` (baseURL + models)
+  - Sync models from `cursor-agent models` into the config (no separate script required)
   - Best-effort ensure `@ai-sdk/openai-compatible` is installed in `~/.config/opencode`
 - `open-cursor sync-models`
   - Run `cursor-agent models`, update provider models in config
@@ -39,14 +41,17 @@ Commands:
 - Optional (later): `open-cursor doctor`
   - Validate cursor-agent presence, login state, and common misconfigurations
 
-Flags (consistent across install/sync/uninstall):
+Flags (keep v1 simple):
 - `--config <path>` default `$XDG_CONFIG_HOME/opencode/opencode.json` (else `~/.config/opencode/opencode.json`)
 - `--plugin-dir <path>` default `$XDG_CONFIG_HOME/opencode/plugin`
-- `--base-url <url>` default `http://127.0.0.1:32124/v1`
 - `--copy` copy plugin-entry instead of symlink
-- `--skip-models` (install only)
 - `--no-backup`
 
+Advanced (optional; only add if needed):
+- `--base-url <url>` override proxy baseURL (default `http://127.0.0.1:32124/v1`).
+  Rationale: users running the proxy on a different host/port.
+- `--skip-models` skip `cursor-agent models` (useful for CI or offline installs).
+
 Backups:
 - Always create `<config>.bak.<timestamp>` unless `--no-backup`.
 
@@ -98,4 +103,3 @@ Add a small integration test harness in Go:
 
 Do not publish to npm for docs-only changes.
 Only publish when user-facing behavior changes (plugin behavior, installer behavior, CLI behavior).
-