fix(cli): remove code bin alias to prevent VS Code CLI collision

docs/MIGRATION.md

@@ -0,0 +1,59 @@
+# Migration Guide
+
+## Removing the `code` CLI alias (v0.10.x → next)
+
+### What changed
+
+The `code` npm bin alias has been removed from `@codemieai/code`. Running `code` after upgrading will no longer invoke the CodeMie CLI.
+
+**Why:** The `code` alias collides with the VS Code CLI (`code`) that is widely installed on developer machines. This collision caused confusing behaviour and is a potential security footgun.
+
+### Who is affected
+
+Users who invoked CodeMie via the `code` command instead of `codemie`.
+
+### What to do
+
+**Option 1 (recommended): Use `codemie` instead.**
+
+```sh
+# Before
+code chat
+
+# After
+codemie chat
+```
+
+All CodeMie commands are available under `codemie` and `codemie-code`.
+
+**Option 2: Add your own shell alias.**
+
+> **Warning:** `alias code=codemie` will shadow the VS Code `code` command. If you use VS Code's CLI (`code .`, `code myfile.ts`), this alias will break it. Only do this if you do not rely on VS Code's `code` CLI, or use a different shorthand (e.g. `alias cm=codemie`).
+
+If you prefer the shorter name and do not use VS Code's `code` CLI, add this to your `~/.zshrc` or `~/.bashrc`:
+
+```sh
+alias code=codemie
+# Or use a shorthand that doesn't conflict:
+# alias cm=codemie
+```
+
+Then reload your shell:
+
+```sh
+source ~/.zshrc   # or ~/.bashrc
+```
+
+### Stale symlink note
+
+If you installed `@codemieai/code` globally **before this release**, npm may have already created a `code` symlink in your global bin directory. Running `npm update -g @codemieai/code` alone does **not** remove the stale symlink — npm does not unlink bin entries that are removed from `package.json` during an update. A full uninstall and reinstall is required.
+
+To verify and clean up:
+
+```sh
+# Check if the stale symlink exists
+which code   # macOS/Linux; on Windows use: where code
+
+# To remove it, uninstall and reinstall the package
+npm uninstall -g @codemieai/code && npm install -g @codemieai/code
+```

docs/superpowers/tasks/2026-07-27-remove-code-bin-alias/actual-complexity.json

@@ -0,0 +1,63 @@
+{
+  "task": "Remove the 'code' npm bin alias from package.json and add docs/MIGRATION.md with user migration instructions.",
+  "generated": "2026-07-27T00:00:00Z",
+  "dimensions": {
+    "component_scope": {
+      "score": 1,
+      "label": "XS",
+      "affected": "package.json bin section, docs/MIGRATION.md",
+      "layers": "Package Config"
+    },
+    "requirements_clarity": {
+      "score": 1,
+      "label": "XS",
+      "status": "Clear",
+      "gaps": null
+    },
+    "technical_risk": {
+      "score": 2,
+      "label": "S",
+      "risk_factors": "Breaking change: existing global npm installations retain a stale 'code' symlink that npm update does not remove; users must fully uninstall and reinstall",
+      "mitigation": "Migration guide (docs/MIGRATION.md) documents the stale-symlink cleanup steps and alternative aliases"
+    },
+    "file_change_estimate": {
+      "score": 2,
+      "label": "S",
+      "modified_files": 1,
+      "modified_file_list": ["package.json"],
+      "new_files": 1,
+      "new_file_list": ["docs/MIGRATION.md"],
+      "affected_dirs": [".", "docs"]
+    },
+    "dependencies": {
+      "score": 1,
+      "label": "XS",
+      "new_packages": [],
+      "version_changes": []
+    },
+    "affected_layers": {
+      "score": 1,
+      "label": "XS",
+      "layers_changed": ["Package Config"],
+      "schema_migration": false,
+      "cross_system": false
+    }
+  },
+  "total": 8,
+  "size": "XS",
+  "band_range": "6-9",
+  "files_changed": 2,
+  "routing": "writing-plans",
+  "key_reasoning": [
+    {
+      "dimension": "technical_risk",
+      "reason": "S (2) not XS because the removal is a breaking change for published npm users: existing global installs retain a stale 'code' symlink that requires a full uninstall/reinstall to clean up — real user-facing impact even though the code change itself is a single-line deletion with trivial rollback"
+    },
+    {
+      "dimension": "file_change_estimate",
+      "reason": "S (2) not XS because the XS band requires no new files; docs/MIGRATION.md is a net-new file, which disqualifies XS even though only 1 file was modified"
+    }
+  ],
+  "red_flags_applied": [],
+  "split_recommendation": null
+}

docs/superpowers/tasks/2026-07-27-remove-code-bin-alias/code-review-final.json

@@ -0,0 +1,59 @@
+{
+  "decision": "request-changes",
+  "rationale": "Three major documentation defects found in MIGRATION.md: wrong npm cleanup command (unlink vs uninstall), Option 2 contradicts the stated security rationale without a caveat, and the claim that npm update -g removes stale symlinks is inaccurate. No spec/story present — acceptance review in no-spec mode (confidence lowered to low). Commit format and security checks pass. 4 defer/dismiss items excluded (Windows 'which' vs 'where', yarn/pnpm coverage, fish/csh shell, vague version range).",
+  "confidence": "low",
+  "risk_flags": ["breaking-change"],
+  "business_review": [],
+  "standards_review": [
+    {
+      "kind": "commit-format",
+      "status": "pass",
+      "notes": "Both commits use valid Conventional Commits types (fix, docs) and scopes (cli); subjects within 100-char limit; ticket reference present."
+    },
+    {
+      "kind": "code-quality",
+      "status": "na",
+      "notes": "No TypeScript files changed; only package.json manifest (1-line deletion) and Markdown documentation."
+    },
+    {
+      "kind": "security",
+      "status": "pass",
+      "notes": "No secrets, credentials, or unsafe patterns introduced. The collision concern in the migration is correctly framed."
+    }
+  ],
+  "findings": [
+    {
+      "id": "CR-001",
+      "severity": "major",
+      "triage": "patch",
+      "file": "docs/MIGRATION.md",
+      "line": 60,
+      "title": "Wrong npm command: `npm unlink -g` should be `npm uninstall -g`",
+      "problem": "`npm unlink -g @codemieai/code` is not a reliable cleanup command. The &&-chain means if unlink fails (package not found or not linked), the reinstall never runs, leaving the user with neither a working package nor a cleaned symlink.",
+      "impact": "Users following the cleanup instructions may end up with either a persistent stale symlink or a broken global install with no installed package.",
+      "recommendation": "Replace `npm unlink -g @codemieai/code && npm install -g @codemieai/code` with `npm uninstall -g @codemieai/code && npm install -g @codemieai/code`."
+    },
+    {
+      "id": "CR-002",
+      "severity": "major",
+      "triage": "patch",
+      "file": "docs/MIGRATION.md",
+      "line": 34,
+      "title": "Option 2 contradicts the stated security rationale without a caveat",
+      "problem": "The guide removes the `code` alias because it 'collides with the VS Code CLI' and is 'a potential security footgun,' then immediately suggests `alias code=codemie` — re-creating the exact same collision in the user's shell without any warning.",
+      "impact": "Users who follow Option 2 re-introduce the very problem the removal was meant to solve: `code .` will open CodeMie instead of VS Code.",
+      "recommendation": "Add an explicit caveat to Option 2 warning that `alias code=codemie` shadows the VS Code `code` command if VS Code is installed. Consider recommending `alias cm=codemie` as a safer shorthand, or at minimum warn users to only do this if they do not use VS Code's `code` CLI."
+    },
+    {
+      "id": "CR-003",
+      "severity": "major",
+      "triage": "patch",
+      "file": "docs/MIGRATION.md",
+      "line": 51,
+      "title": "Inaccurate claim: `npm update -g` does not reliably remove stale bin symlinks",
+      "problem": "The guide states 'Upgrading via `npm update -g @codemieai/code` removes it for a fresh install of the new package' — this is inaccurate. `npm update -g` does not unlink and relink bin entries when a key is removed from package.json; the stale `code` symlink persists after an update.",
+      "impact": "Users who run `npm update -g` believing it cleans up the symlink will still have a stale `code` command pointing to codemie after upgrading.",
+      "recommendation": "Correct the statement: users must run `npm uninstall -g @codemieai/code && npm install -g @codemieai/code` to clear the stale symlink. Remove or correct the misleading `npm update -g` claim."
+    }
+  ]
+}

docs/superpowers/tasks/2026-07-27-remove-code-bin-alias/decisions.jsonl

@@ -0,0 +1 @@
+{"ts":"2026-07-27T09:00:00Z","gate_id":"code-review.final","mode":"hitl","verdict":{"decision":"approve","rationale":"User approved with inline fixes for CR-001, CR-002, CR-003.","follow_ups":["fix CR-001: npm unlink → npm uninstall","fix CR-002: add VS Code caveat to Option 2","fix CR-003: correct npm update-g claim"],"confidence":"high","source":"hitl"},"escalated":false,"prior_context":{"question":"3 major findings in docs/MIGRATION.md","phase":5,"risk_flags":["breaking-change"],"artifact_refs":["docs/superpowers/tasks/2026-07-27-remove-code-bin-alias/plan.md","docs/superpowers/tasks/2026-07-27-remove-code-bin-alias/code-review.diff"],"prior_orchestrator_verdict":"docs/superpowers/tasks/2026-07-27-remove-code-bin-alias/code-review-final.json"}}

docs/superpowers/tasks/2026-07-27-remove-code-bin-alias/events.jsonl

@@ -0,0 +1,3 @@
+{"event":"lifecycle_emission","intent":"artifact_published","artifact_kind":"plan","status":"failed"}
+{"schema":1,"ts":"2026-07-27T09:00:00Z","event":"decision.recorded","run_id":null,"phase":5,"actor":"decision-router","summary":"Decision recorded for code-review.final: approve","artifacts":["decisions.jsonl"],"data":{"gate_id":"code-review.final","mode":"hitl","decision":"approve","source":"hitl","escalated":false,"prior_context":{"question":"3 major findings in docs/MIGRATION.md","options":["Approve — fix findings inline","Approve — ship as-is","Request changes — pause for me to review"],"phase":5,"risk_flags":["breaking-change"],"artifact_refs":["plan.md","code-review.diff"]}}}
+{"event":"lifecycle_emission","intent":"record_complexity_score","assessment_mode":"actual","status":"failed"}

docs/superpowers/tasks/2026-07-27-remove-code-bin-alias/gate-plan.json

@@ -0,0 +1,16 @@
+{
+  "schema": 1,
+  "runner": "npm",
+  "gates": [
+    {"id": "license-check", "command": "npm run license-check", "available": true},
+    {"id": "lint",          "command": "npm run lint",          "available": true},
+    {"id": "typecheck",     "command": "npm run typecheck",     "available": true},
+    {"id": "build",         "command": "npm run build",         "available": true},
+    {"id": "unit",          "command": "npm run test:unit",     "available": true},
+    {"id": "integration",   "command": "npm run test:integration", "available": true},
+    {"id": "commitlint",    "command": "npm run commitlint:last","available": true},
+    {"id": "ui",            "command": "",                      "available": false}
+  ],
+  "ui_globs": ["\\.(tsx|jsx|css|html|vue|svelte)$", "src/(ui|frontend|components)/"],
+  "detected_at": "2026-07-27T09:10:00Z"
+}

docs/superpowers/tasks/2026-07-27-remove-code-bin-alias/plan.md

@@ -0,0 +1,166 @@
+# Remove `code` bin alias Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Remove the `"code"` npm bin entry from `package.json` to prevent collisions with VS Code's `code` CLI, and document the migration path for existing users.
+
+**Architecture:** One-line deletion from `package.json` eliminates the npm-level alias at install time. A new `docs/MIGRATION.md` file explains the breaking change, the stale-symlink caveat (existing installs retain the symlink until reinstall), and two workaround options for users who relied on the `code` shorthand.
+
+**Tech Stack:** npm bin declarations, Markdown
+
+## Global Constraints
+
+- ES modules only — no `require()` in any changed file
+- No installer opt-in (`postinstall.mjs` is out of scope for this ticket)
+- Migration note must mention the stale-symlink limitation and both workaround options
+- Ticket: EPMCDME-13589
+
+---
+
+### Task 1: Remove `code` from `package.json` bin block
+
+**Test-first:** no — manifest change, not runtime behaviour. Verification is a `grep` assertion on the file.
+
+**Files:**
+- Modify: `package.json:10` — delete the `"code"` entry
+
+**Interfaces:**
+- Consumes: nothing
+- Produces: `package.json` with `bin` block that no longer declares `"code"` — `codemie`, `codemie-code`, and all other entries remain intact
+
+- [ ] **Step 1: Delete the `"code"` bin line**
+
+Open `package.json`. The `bin` block currently looks like:
+
+```json
+"bin": {
+  "codemie": "./bin/codemie.js",
+  "code": "./bin/codemie.js",
+  "codemie-code": "./bin/agent-executor.js",
+  ...
+```
+
+Remove exactly this line (line 10):
+
+```
+  "code": "./bin/codemie.js",
+```
+
+After the edit:
+
+```json
+"bin": {
+  "codemie": "./bin/codemie.js",
+  "codemie-code": "./bin/agent-executor.js",
+  ...
+```
+
+- [ ] **Step 2: Verify `code` is absent and JSON is valid**
+
+```bash
+node -e "const p = JSON.parse(require('fs').readFileSync('package.json','utf8')); console.log(Object.keys(p.bin));"
+```
+
+Expected output must include `codemie` and `codemie-code` but must NOT include `code`.
+
+```bash
+grep '"code"' package.json | grep -v codemie-code | grep -v codemie-claude
+```
+
+Expected: no output.
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add package.json
+git commit -m "fix(cli): remove \`code\` bin alias from package.json (EPMCDME-13589)"
+```
+
+---
+
+### Task 2: Create migration note
+
+**Test-first:** no — documentation task.
+
+**Files:**
+- Create: `docs/MIGRATION.md`
+
+**Interfaces:**
+- Consumes: nothing
+- Produces: `docs/MIGRATION.md` — top-level migration guide
+
+- [ ] **Step 1: Create `docs/MIGRATION.md`**
+
+```markdown
+# Migration Guide
+
+## Removing the `code` CLI alias (v0.10.x → next)
+
+### What changed
+
+The `code` npm bin alias has been removed from `@codemieai/code`. Running `code` after upgrading will no longer invoke the CodeMie CLI.
+
+**Why:** The `code` alias collides with the VS Code CLI (`code`) that is widely installed on developer machines. This collision caused confusing behaviour and is a potential security footgun.
+
+### Who is affected
+
+Users who invoked CodeMie via the `code` command instead of `codemie`.
+
+### What to do
+
+**Option 1 (recommended): Use `codemie` instead.**
+
+​```sh
+# Before
+code chat
+
+# After
+codemie chat
+​```
+
+All CodeMie commands are available under `codemie` and `codemie-code`.
+
+**Option 2: Add your own shell alias.**
+
+If you prefer the shorter name, add this to your `~/.zshrc` or `~/.bashrc`:
+
+​```sh
+alias code=codemie
+​```
+
+Then reload your shell:
+
+​```sh
+source ~/.zshrc   # or ~/.bashrc
+​```
+
+### Stale symlink note
+
+If you installed `@codemieai/code` globally **before this release**, npm may have already created a `code` symlink in your global bin directory. Upgrading via `npm update -g @codemieai/code` removes it for a fresh install of the new package, but existing symlinks from older installs may persist.
+
+To verify and clean up:
+
+​```sh
+# Check if the stale symlink exists
+which code
+
+# If it still points to codemie, remove it manually
+npm unlink -g @codemieai/code && npm install -g @codemieai/code
+​```
+```
+
+- [ ] **Step 2: Verify file was created**
+
+```bash
+ls -la docs/MIGRATION.md
+grep -c "stale symlink" docs/MIGRATION.md
+```
+
+Expected: file exists, grep returns `1`.
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add docs/MIGRATION.md
+git commit -m "docs: add MIGRATION.md for \`code\` bin alias removal (EPMCDME-13589)"
+```

docs/superpowers/tasks/2026-07-27-remove-code-bin-alias/qa-report.md

@@ -0,0 +1,23 @@
+# QA Gate Report — remove-code-bin-alias
+
+**Branch**: EPMCDME-13589
+**Runner**: npm
+**Started**: 2026-07-27T09:10:00Z
+**Status**: PASSED
+
+## Gates
+
+| Gate         | Status  | Command                       | Notes |
+|--------------|---------|-------------------------------|-------|
+| license-check | PASS   | `npm run license-check`       | All dependencies have compatible licenses |
+| lint          | PASS   | `npm run lint`                | 0 errors, 0 warnings |
+| typecheck     | PASS   | `npm run typecheck`           | No TypeScript diagnostics |
+| build         | PASS   | `npm run build`               | dist/ rebuilt cleanly; copy-plugin succeeded |
+| unit          | PASS   | `npm run test:unit`           | 162 test files, 2382 tests passed, 1 skipped |
+| integration   | PASS   | `npm run test:integration`    | 28 test files, 196 tests passed, 11 skipped |
+| commitlint    | PASS   | `npm run commitlint:last`     | 0 problems, 0 warnings |
+| ui            | SKIPPED | —                            | No UI surface files changed (.tsx/.jsx/.css/.html) |
+
+## Drift signal
+
+no