4runr-cursor-setup 0.1.17 → 0.1.18

package/README.md

@@ -1,6 +1,34 @@
 # 4runr-cursor-setup
 
-**Full Git usage guide:** [docs/USAGE_GIT.md](docs/USAGE_GIT.md)
+**Documentation:**
+- [Command Reference](docs/COMMANDS.md) — Complete command and flag documentation
+- [Git Usage Guide](docs/USAGE_GIT.md) — End-to-end Git repo usage guide
+
+## New Repo Quick Start
+
+**PowerShell:**
+```powershell
+# Step 1: Repair / normalize repo (safe)
+npx -y 4runr-cursor-setup@latest doctor --fix --purge-orphans --strict
+
+# Step 2: Install core commands
+npx -y 4runr-cursor-setup@latest add core
+
+# Step 3: Verify health
+npx -y 4runr-cursor-setup@latest doctor --strict
+```
+
+**Bash:**
+```bash
+# Step 1: Repair / normalize repo (safe)
+npx -y 4runr-cursor-setup@latest doctor --fix --purge-orphans --strict
+
+# Step 2: Install core commands
+npx -y 4runr-cursor-setup@latest add core
+
+# Step 3: Verify health
+npx -y 4runr-cursor-setup@latest doctor --strict
+```
 
 ## Golden Path
 
@@ -72,26 +100,100 @@ npx -y 4runr-cursor-setup@latest add core --dry-run
 - `governance`: Governance commands (decision, scope-change)
 - `debugging`: Debugging commands (repro, verify)
 
-## Troubleshooting
+## Common Scenarios
 
-### npx Cache Issues
+### "0 files written" When Adding a Group
 
-If `npx -y 4runr-cursor-setup@latest` fails with `ETARGET` but the version exists on npm:
+**Reasons and exact next steps:**
 
-This is an npx cache desync. Clear the cache and retry:
+1. **Already installed and managed** (normal)
+   - Files exist, have marker, and are in manifest
+   - **Action:** Nothing to do. This is expected.
 
-**PowerShell:**
+2. **Orphan marker files**
+   - Files have marker but aren't in manifest
+   - **Fix:**
+     ```bash
+     npx -y 4runr-cursor-setup@latest doctor --purge-orphans
+     npx -y 4runr-cursor-setup@latest add planning
+     ```
+     (Replace `planning` with the actual group name)
+
+3. **Unmanaged collision**
+   - Files exist without marker (user-created)
+   - Tool will never overwrite these
+   - **Fix (manual):**
+     ```bash
+     # Rename or move the colliding file
+     mv .cursor/commands/4runr-start.md .cursor/commands/4runr-start.md.backup
+     # Then re-run add
+     npx -y 4runr-cursor-setup@latest add core
+     ```
+
+### Orphan Marker Files
+
+**What they are:**
+- Files in `.cursor/commands/` with the managed marker (`<!-- managed-by: 4runr-cursor-setup -->`) but not listed in the manifest
+
+**Why they exist:**
+- Manifest was deleted or reset
+- Files were manually created with marker
+- Manifest drift
+
+**Fix:**
+```bash
+npx -y 4runr-cursor-setup@latest doctor --purge-orphans
+```
+
+**What it does:**
+- Deletes only orphan marker files (safe)
+- Never deletes managed files or unmarked files
+
+### Unmanaged Collision
+
+**What it is:**
+- A file exists at a path where the tool wants to install a template, but the file doesn't have the managed marker
+
+**Why it happens:**
+- User created a file manually
+- File was created before tool installation
+
+**Resolution (manual):**
+1. Rename or move the colliding file:
+   ```bash
+   mv .cursor/commands/4runr-start.md .cursor/commands/4runr-start.md.backup
+   ```
+2. Re-run add:
+   ```bash
+   npx -y 4runr-cursor-setup@latest add core
+   ```
+
+**Important:** The tool will never overwrite unmanaged files, even with `--force`.
+
+### ETARGET / npx Cache Desync
+
+**Symptom:**
+- `npx -y 4runr-cursor-setup@latest` fails with `ETARGET` but the version exists on npm
+
+**Cause:**
+- npx cache is out of sync with npm registry
+
+**Fix (PowerShell):**
 ```powershell
 npm cache clean --force
 Remove-Item -Recurse -Force "$env:LOCALAPPDATA\npm-cache\_npx" -ErrorAction SilentlyContinue
 ```
 
-**Bash:**
+**Fix (Bash):**
 ```bash
 npm cache clean --force
 rm -rf ~/.npm/_npx
 ```
 
+**Then retry your command.**
+
+## Troubleshooting
+
 ### PowerShell Error: The '<' operator is reserved for future use
 
 **Cause:** Copied placeholder like `GROUP` from documentation without replacing it.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "4runr-cursor-setup",
-  "version": "0.1.17",
+  "version": "0.1.18",
   "description": "",
   "main": "index.js",
   "scripts": {