codeforge-dev 1.9.0 → 1.10.0

package/.devcontainer/plugins/devs-marketplace/plugins/code-directive/skills/spec-refine/SKILL.md

@@ -0,0 +1,194 @@
+---
+name: spec-refine
+description: >-
+  This skill should be used when the user asks to "refine a spec",
+  "review spec assumptions", "validate spec decisions", "question the
+  spec", "iterate on the spec", "check spec for assumptions", "approve
+  the spec", "walk me through the spec", or needs iterative
+  user-driven refinement of a specification through structured
+  questioning rounds.
+version: 0.1.0
+---
+
+# Iterative Spec Refinement
+
+## Mental Model
+
+A draft spec is a hypothesis, not a commitment. Every requirement, tech decision, and scope boundary in a draft is an assumption until the user explicitly validates it. This skill systematically mines a spec for unvalidated assumptions, presents each to the user for review via structured questions, and iterates until every decision has explicit user approval.
+
+No implementation begins on a spec with `**Approval:** draft`. This skill is the gate.
+
+---
+
+## Workflow
+
+### Step 1: Load & Inventory
+
+Find the target spec:
+- If `$ARGUMENTS` contains a path or feature name, use it directly
+- Otherwise, glob `.specs/**/*.md` and ask the user which spec to refine
+
+Read the full spec. Catalog:
+- Every section and whether it has content
+- The `**Approval:**` status (should be `draft`)
+- All requirements and their current markers (`[assumed]` vs `[user-approved]`)
+- The `## Open Questions` section (if any)
+- The `## Resolved Questions` section (if any)
+
+If the spec is already `**Approval:** user-approved` and all requirements are `[user-approved]`, report this and ask if the user wants to re-review anyway.
+
+### Step 2: Assumption Mining
+
+Scan each section systematically for unvalidated decisions. Look for:
+
+| Category | What to look for |
+|----------|-----------------|
+| **Tech decisions** | Database choices, auth mechanisms, API formats, libraries, protocols |
+| **Scope boundaries** | What's included/excluded without stated rationale |
+| **Performance targets** | Numbers (response times, limits, thresholds) that were assumed |
+| **Architecture choices** | Where logic lives, service boundaries, data flow patterns |
+| **Behavioral defaults** | Error handling, retry logic, fallback behavior, timeout values |
+| **Unstated dependencies** | Systems, services, or libraries the spec assumes exist |
+| **Security assumptions** | Auth requirements, data sensitivity, access control patterns |
+
+For each assumption found, prepare a question with 2-4 alternatives including the current assumption.
+
+Present findings via `AskUserQuestion` in rounds of 1-4 questions. Group related assumptions together. Example:
+
+```
+Question: "Which authentication mechanism should this feature use?"
+Options:
+- JWT with refresh tokens (current assumption)
+- Session cookies with httpOnly flag
+- OAuth2 with external provider
+```
+
+Record each answer. After the user responds, check: did any answer reveal new assumptions or contradictions? If yes, add follow-up questions to the queue.
+
+### Step 3: Requirement Validation
+
+Walk through every requirement tagged `[assumed]`:
+
+1. **Read the requirement** aloud to the user (via the question text)
+2. **Assess** — is it specific? testable? complete?
+3. **Present via AskUserQuestion** with options:
+   - Approve as-is
+   - Needs revision (user provides direction via "Other")
+   - Remove (not needed)
+   - Defer to Open Questions (not decidable yet)
+
+Process requirements in batches of 1-4 per question round. Prioritize:
+- Requirements with the most ambiguity first
+- Requirements that other requirements depend on
+- Requirements involving tech decisions or external systems
+
+For approved requirements, update the marker from `[assumed]` to `[user-approved]`.
+For revised requirements, rewrite per user direction and mark `[user-approved]`.
+For removed requirements, delete them.
+For deferred requirements, move to `## Open Questions`.
+
+### Step 4: Acceptance Criteria Review
+
+For each acceptance criterion:
+1. Is it measurable and testable?
+2. Does it map to a specific requirement?
+3. Are there requirements without corresponding criteria?
+
+Present gaps to the user:
+- Missing criteria for existing requirements
+- Criteria that don't map to any requirement
+- Criteria with vague or unmeasurable outcomes
+
+Get approval on each criterion or batch of related criteria.
+
+### Step 5: Scope & Dependency Audit
+
+Review the spec from four perspectives:
+
+**User perspective:**
+- Does the feature solve the stated problem?
+- Are there user needs not addressed?
+- Is the scope too broad or too narrow?
+
+**Developer perspective:**
+- Is this implementable with the current architecture?
+- Are the key files accurate?
+- Are there missing technical constraints?
+
+**Security perspective:**
+- Are there data sensitivity issues?
+- Is authentication/authorization addressed?
+- Are there input validation gaps?
+
+**Operations perspective:**
+- Deployment considerations?
+- Monitoring and observability needs?
+- Rollback strategy needed?
+
+Surface any missing items via `AskUserQuestion`. Get explicit decisions on scope boundaries and dependency completeness.
+
+### Step 6: Final Approval
+
+1. Present a summary of all changes made during refinement:
+   - Assumptions resolved (count)
+   - Requirements approved/revised/removed
+   - New criteria added
+   - Scope changes
+
+2. Ask for final approval via `AskUserQuestion`:
+   - "Approve spec — all decisions validated, ready for implementation"
+   - "More refinement needed — specific concerns remain"
+
+3. On approval:
+   - Set `**Approval:** user-approved`
+   - Update `**Last Updated:**` to today
+   - Verify all requirements are tagged `[user-approved]`
+   - Populate `## Resolved Questions` with the decision trail from this session
+
+4. On "more refinement needed":
+   - Ask what concerns remain
+   - Loop back to the relevant phase
+
+---
+
+## Convergence Rules
+
+- After each phase, check: did answers from this phase raise new questions? If yes, run another questioning round before advancing.
+- The skill does NOT terminate until ALL of:
+  - Every `[assumed]` requirement is resolved (approved, revised, removed, or deferred)
+  - All acceptance criteria are reviewed
+  - The user gives explicit final approval
+- If the user wants to stop early, leave `**Approval:** draft` and note remaining items in `## Open Questions`.
+
+---
+
+## Resolved Questions Format
+
+Each resolved question follows this format:
+
+```markdown
+1. **[Decision topic]** — [Chosen option] (user-approved, YYYY-MM-DD)
+   - Options considered: [list]
+   - Rationale: [brief user reasoning or context]
+```
+
+Keep entries concise — decision + options + rationale in 2-3 lines each.
+
+---
+
+## Ambiguity Policy
+
+- If the spec has no `**Approval:**` field, treat it as `draft` and add the field.
+- If requirements lack `[assumed]`/`[user-approved]` tags, treat all as `[assumed]`.
+- If the user says "approve everything" without reviewing individual items, warn that blanket approval defeats the purpose — offer to fast-track by presenting summaries of each batch.
+- If the spec is very short (< 30 lines), the full 6-phase process may be unnecessary. Adapt: merge phases 2-4 into a single review pass. Still require explicit final approval.
+- If the user provides a feature name that matches multiple specs, list them and ask which to refine.
+
+---
+
+## Anti-Patterns
+
+- **Rubber-stamping**: Presenting assumptions and immediately suggesting "approve all." Every assumption gets its own question with real alternatives.
+- **Leading questions**: "Should we use JWT as planned?" is leading. Present alternatives neutrally: "Which auth mechanism should this feature use? Options: JWT, sessions, OAuth2."
+- **Skipping phases**: Every phase surfaces different types of assumptions. Don't skip phases even if earlier phases had few findings.
+- **Silent upgrades**: Never change `[assumed]` to `[user-approved]` without presenting the item to the user first.

package/.devcontainer/plugins/devs-marketplace/plugins/code-directive/skills/spec-update/SKILL.md

@@ -18,6 +18,16 @@ This is not optional. Every implementation ends with a spec update.
 
 ---
 
+## Approval Gate
+
+Before performing an as-built update, check the spec's `**Approval:**` status:
+- If `user-approved` → proceed with the update
+- If `draft` → warn the user: "This spec is still `draft`. It should have gone through `/spec-refine` before implementation. Run `/spec-refine` now to validate, or proceed with the as-built update if the user confirms."
+
+This is a warning, not a blocker — the user decides whether to refine first or update as-is.
+
+---
+
 ## The 6-Step Workflow
 
 ### Step 1: Find the Spec
@@ -72,6 +82,8 @@ Verify paths exist before listing them. Use absolute project-relative paths.
 
 - Set `**Last Updated:**` to today's date (YYYY-MM-DD)
 - Verify `**Version:**` is correct
+- Preserve the `**Approval:**` status — do NOT downgrade `user-approved` to `draft`
+- If the as-built update introduces new decisions not in the original spec, add them to `## Resolved Questions` if the user confirmed them, or `## Open Questions` if they were assumed during implementation
 
 ---
 
@@ -109,7 +121,10 @@ Before finishing the update:
 - [ ] Implementation Notes document deviations from original spec
 - [ ] File paths in Key Files are accurate and verified
 - [ ] Last Updated date is today
-- [ ] Spec is still ≤200 lines
+- [ ] `**Approval:**` status is preserved (not downgraded)
+- [ ] New implementation decisions are tracked in Resolved Questions or Open Questions
+- [ ] If the spec has grown past ~200 lines, note it and suggest splitting in a future pass
+- [ ] If `**Approval:**` is still `draft`, user was warned and confirmed proceeding
 - [ ] No source code was pasted inline (references only)
 
 ---
@@ -122,3 +137,6 @@ Before finishing the update:
   requirements to match what was built.
 - If acceptance criteria are ambiguous about whether they're met, note the
   ambiguity in Discrepancies rather than checking them off optimistically.
+- A spec-reminder advisory hook fires at Stop when code was modified but
+  specs weren't updated. If you see "[Spec Reminder]" in context, that's
+  the trigger — use this skill to resolve it.

package/.devcontainer/plugins/devs-marketplace/plugins/code-directive/skills/specification-writing/SKILL.md

@@ -30,11 +30,11 @@ Write specifications with a hostile reader in mind -- someone who will interpret
 
 ---
 
-## Spec Sizing & AI Context Rules
+## Spec Sizing Guidelines
 
 Specifications are loaded into AI context windows with limited capacity. Design for consumption.
 
-**Hard limit:** ≤200 lines per spec file. If a feature needs more, split into sub-specs (one per sub-feature) with a ≤50 line overview linking them.
+**Recommended target:** ~200 lines per spec file. When a spec grows beyond that, consider splitting into sub-specs (one per sub-feature) with a concise overview linking them. Complex features may justify longer specs — completeness matters more than hitting a number.
 
 **Reference, don't reproduce:** Never inline source code, SQL DDL, Pydantic models, or TypeScript interfaces. Reference the file path and line range instead. The code is the source of truth — duplicated snippets go stale silently.
 
@@ -179,9 +179,10 @@ Every spec file starts with metadata:
 **Version:** v0.X.0
 **Status:** implemented | partial | planned
 **Last Updated:** YYYY-MM-DD
+**Approval:** draft | user-approved
 ```
 
-Status tells you whether to trust it, version tells you where it belongs, last-updated tells you when it was last verified.
+Status tells you whether to trust it, version tells you where it belongs, last-updated tells you when it was last verified. Approval tells you whether decisions in the spec have been explicitly validated by the user (`user-approved`) or are AI-generated hypotheses (`draft`).
 
 ### 1. Problem Statement
 What problem does this feature solve? Who has this problem? What's the cost of not solving it? (2-3 sentences)
@@ -218,20 +219,22 @@ so that [I can detect suspicious reset patterns].
 Use EARS format. Number each requirement for traceability:
 
 ```markdown
-- FR-1: When a user requests a password reset, the system shall send a reset email
+- FR-1 [assumed]: When a user requests a password reset, the system shall send a reset email
   to the registered email address within 60 seconds.
-- FR-2: The reset link shall contain a cryptographically random token (min 32 bytes).
-- FR-3: If the reset token is expired or already used, then the system shall display
+- FR-2 [assumed]: The reset link shall contain a cryptographically random token (min 32 bytes).
+- FR-3 [assumed]: If the reset token is expired or already used, then the system shall display
   an error message and offer to send a new reset email.
+
+Tag each requirement `[assumed]` when first written. Requirements become `[user-approved]` only after explicit user validation via `/spec-refine`.
 ```
 
 ### 5. Non-Functional Requirements
 Performance, security, scalability, accessibility:
 
 ```markdown
-- NFR-1: The password reset endpoint shall respond within 200ms (p95).
-- NFR-2: Reset tokens shall be stored as bcrypt hashes, not plaintext.
-- NFR-3: The reset flow shall be accessible with screen readers (WCAG 2.1 AA).
+- NFR-1 [assumed]: The password reset endpoint shall respond within 200ms (p95).
+- NFR-2 [assumed]: Reset tokens shall be stored as bcrypt hashes, not plaintext.
+- NFR-3 [assumed]: The reset flow shall be accessible with screen readers (WCAG 2.1 AA).
 ```
 
 ### 6. Edge Cases
@@ -249,13 +252,16 @@ The cases nobody thinks about until they happen:
 ### 7. Out of Scope
 Explicit non-goals to prevent scope creep (can reference the Scope section or expand here).
 
-### 8. Key Files
+### 8. Resolved Questions
+Decisions explicitly approved by the user via `/spec-refine`. Each entry: decision topic, chosen option, options considered, date, brief rationale. This section starts empty and is populated during the refinement process.
+
+### 9. Key Files
 Source files most relevant to this feature — paths an implementer should read.
 
-### 9. Implementation Notes
+### 10. Implementation Notes
 Post-implementation only. Capture deviations from the original spec — what changed and why.
 
-### 10. Discrepancies
+### 11. Discrepancies
 Gaps between spec intent and actual build. Prevents the next session from re-planning decided work.
 
 ---
@@ -309,6 +315,7 @@ These defaults apply when the user does not specify a preference. State the assu
 - **Edge cases:** Always include at least: empty input, maximum input, concurrent access, and external service failure.
 - **Out of scope:** Always include an out-of-scope section, even if brief, to establish boundaries.
 - **Numbering:** Number all requirements (FR-1, NFR-1) for traceability in code reviews and tests.
+- **Approval markers:** All requirements start as `[assumed]`. Only `/spec-refine` with explicit user validation upgrades them to `[user-approved]`. Spec-level `**Approval:**` starts as `draft` and becomes `user-approved` only when all requirements are `[user-approved]`.
 
 ---
 

package/.devcontainer/scripts/check-setup.sh

@@ -5,34 +5,37 @@
 echo "CodeForge Setup Check"
 echo "━━━━━━━━━━━━━━━━━━━━"
 
-PASS=0; FAIL=0; WARN=0
+PASS=0
+FAIL=0
+WARN=0
 
 check() {
-    local label="$1" cmd="$2"
-    if eval "$cmd" >/dev/null 2>&1; then
-        printf "  ✓ %s\n" "$label"
-        PASS=$((PASS + 1))
-    else
-        printf "  ✗ %s\n" "$label"
-        FAIL=$((FAIL + 1))
-    fi
+	local label="$1" cmd="$2"
+	if eval "$cmd" >/dev/null 2>&1; then
+		printf "  ✓ %s\n" "$label"
+		PASS=$((PASS + 1))
+	else
+		printf "  ✗ %s\n" "$label"
+		FAIL=$((FAIL + 1))
+	fi
 }
 
 warn_check() {
-    local label="$1" cmd="$2"
-    if eval "$cmd" >/dev/null 2>&1; then
-        printf "  ✓ %s\n" "$label"
-        PASS=$((PASS + 1))
-    else
-        printf "  ⚠ %s\n" "$label"
-        WARN=$((WARN + 1))
-    fi
+	local label="$1" cmd="$2"
+	if eval "$cmd" >/dev/null 2>&1; then
+		printf "  ✓ %s\n" "$label"
+		PASS=$((PASS + 1))
+	else
+		printf "  ⚠ %s\n" "$label"
+		WARN=$((WARN + 1))
+	fi
 }
 
 echo ""
 echo "Core:"
 check "Claude Code installed" "command -v claude"
-check "cc alias available" "type cc"
+warn_check "Claude native binary" "[ -x /usr/local/bin/claude ]"
+check "cc alias configured" "grep -q 'alias cc=' ~/.bashrc 2>/dev/null || grep -q 'alias cc=' ~/.zshrc 2>/dev/null"
 check "Config directory exists" "[ -d '${CLAUDE_CONFIG_DIR:-/workspaces/.claude}' ]"
 check "Settings file exists" "[ -f '${CLAUDE_CONFIG_DIR:-/workspaces/.claude}/settings.json' ]"
 
@@ -54,10 +57,6 @@ echo ""
 echo "Development:"
 warn_check "biome" "command -v biome"
 warn_check "ruff" "command -v ruff"
-warn_check "dprint" "command -v dprint"
-warn_check "shfmt" "command -v shfmt"
-warn_check "shellcheck" "command -v shellcheck"
-warn_check "hadolint" "command -v hadolint"
 warn_check "ast-grep" "command -v ast-grep"
 warn_check "tmux" "command -v tmux"
 
@@ -66,7 +65,7 @@ echo "━━━━━━━━━━━━━━━━━━━━"
 echo "  $PASS passed, $FAIL failed, $WARN warnings"
 
 if [ $FAIL -gt 0 ]; then
-    echo ""
-    echo "  Run 'cc-tools' for detailed version info."
-    exit 1
+	echo ""
+	echo "  Run 'cc-tools' for detailed version info."
+	exit 1
 fi

package/.devcontainer/scripts/setup-aliases.sh

@@ -6,82 +6,94 @@ CLAUDE_DIR="${CLAUDE_CONFIG_DIR:?CLAUDE_CONFIG_DIR not set}"
 echo "[setup-aliases] Configuring Claude aliases..."
 
 # Simple alias definitions (not functions — functions don't behave reliably across shell contexts)
-ALIAS_CC='alias cc='"'"'CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 command claude --system-prompt-file "$CLAUDE_CONFIG_DIR/system-prompt.md" --permission-mode plan --allow-dangerously-skip-permissions'"'"''
-ALIAS_CLAUDE='alias claude='"'"'CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 command claude --system-prompt-file "$CLAUDE_CONFIG_DIR/system-prompt.md" --permission-mode plan --allow-dangerously-skip-permissions'"'"''
-ALIAS_CCRAW='alias ccraw="command claude"'
+# Aliases reference $_CLAUDE_BIN which is resolved at shell startup to prefer the native binary.
+ALIAS_CC='alias cc='"'"'CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 command "$_CLAUDE_BIN" --system-prompt-file "$CLAUDE_CONFIG_DIR/system-prompt.md" --permission-mode plan --allow-dangerously-skip-permissions'"'"''
+ALIAS_CLAUDE='alias claude='"'"'CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 command "$_CLAUDE_BIN" --system-prompt-file "$CLAUDE_CONFIG_DIR/system-prompt.md" --permission-mode plan --allow-dangerously-skip-permissions'"'"''
+ALIAS_CCRAW='alias ccraw='"'"'command "$_CLAUDE_BIN"'"'"''
 
 for rc in ~/.bashrc ~/.zshrc; do
-    if [ -f "$rc" ]; then
-        # --- Backup before modifying ---
-        cp "$rc" "${rc}.bak.$(date +%s)" 2>/dev/null || true
-        # Clean old backups (keep last 3)
-        ls -t "${rc}.bak."* 2>/dev/null | tail -n +4 | xargs rm -f 2>/dev/null || true
+	if [ -f "$rc" ]; then
+		# --- Backup before modifying ---
+		cp "$rc" "${rc}.bak.$(date +%s)" 2>/dev/null || true
+		# Clean old backups (keep last 3)
+		ls -t "${rc}.bak."* 2>/dev/null | tail -n +4 | xargs rm -f 2>/dev/null || true
 
-        # --- Cleanup old definitions ---
+		# --- Cleanup old definitions ---
 
-        # Remove old cc alias
-        if grep -q "alias cc=" "$rc" 2>/dev/null; then
-            sed -i '/alias cc=/d' "$rc"
-            echo "[setup-aliases] Removed old cc alias from $(basename $rc)"
-        fi
-        # Remove old cc function (single-line or multi-line)
-        if grep -q "^cc()" "$rc" 2>/dev/null; then
-            sed -i '/^cc() {/,/^}/d' "$rc"
-            echo "[setup-aliases] Removed old cc function from $(basename $rc)"
-        fi
-        # Remove old _claude_with_config function
-        if grep -q "^_claude_with_config()" "$rc" 2>/dev/null; then
-            sed -i '/^_claude_with_config() {/,/^}/d' "$rc"
-            echo "[setup-aliases] Removed old _claude_with_config function from $(basename $rc)"
-        fi
-        # Remove old claude function override
-        if grep -q "^claude() {" "$rc" 2>/dev/null; then
-            sed -i '/^claude() { _claude_with_config/d' "$rc"
-            echo "[setup-aliases] Removed old claude function from $(basename $rc)"
-        fi
-        # Remove old claude alias
-        if grep -q "alias claude=" "$rc" 2>/dev/null; then
-            sed -i '/alias claude=/d' "$rc"
-        fi
-        # Remove old ccraw alias
-        if grep -q "alias ccraw=" "$rc" 2>/dev/null; then
-            sed -i '/alias ccraw=/d' "$rc"
-        fi
-        # Remove old specwright alias
-        if grep -q "alias specwright=" "$rc" 2>/dev/null; then
-            sed -i '/alias specwright=/d' "$rc"
-        fi
-        # Remove old cc-tools/check-setup functions
-        if grep -q "^cc-tools()" "$rc" 2>/dev/null; then
-            sed -i '/^cc-tools() {/,/^}/d' "$rc"
-        fi
-        if grep -q "alias check-setup=" "$rc" 2>/dev/null; then
-            sed -i '/alias check-setup=/d' "$rc"
-        fi
+		# Remove old cc alias
+		if grep -q "alias cc=" "$rc" 2>/dev/null; then
+			sed -i '/alias cc=/d' "$rc"
+			echo "[setup-aliases] Removed old cc alias from $(basename $rc)"
+		fi
+		# Remove old cc function (single-line or multi-line)
+		if grep -q "^cc()" "$rc" 2>/dev/null; then
+			sed -i '/^cc() {/,/^}/d' "$rc"
+			echo "[setup-aliases] Removed old cc function from $(basename $rc)"
+		fi
+		# Remove old _claude_with_config function
+		if grep -q "^_claude_with_config()" "$rc" 2>/dev/null; then
+			sed -i '/^_claude_with_config() {/,/^}/d' "$rc"
+			echo "[setup-aliases] Removed old _claude_with_config function from $(basename $rc)"
+		fi
+		# Remove old claude function override
+		if grep -q "^claude() {" "$rc" 2>/dev/null; then
+			sed -i '/^claude() { _claude_with_config/d' "$rc"
+			echo "[setup-aliases] Removed old claude function from $(basename $rc)"
+		fi
+		# Remove old claude alias
+		if grep -q "alias claude=" "$rc" 2>/dev/null; then
+			sed -i '/alias claude=/d' "$rc"
+		fi
+		# Remove old ccraw alias
+		if grep -q "alias ccraw=" "$rc" 2>/dev/null; then
+			sed -i '/alias ccraw=/d' "$rc"
+		fi
+		# Remove old specwright alias
+		if grep -q "alias specwright=" "$rc" 2>/dev/null; then
+			sed -i '/alias specwright=/d' "$rc"
+		fi
+		# Remove old cc-tools/check-setup functions
+		if grep -q "^cc-tools()" "$rc" 2>/dev/null; then
+			sed -i '/^cc-tools() {/,/^}/d' "$rc"
+		fi
+		if grep -q "alias check-setup=" "$rc" 2>/dev/null; then
+			sed -i '/alias check-setup=/d' "$rc"
+		fi
+		# --- Add environment and aliases (idempotent) ---
+		# Guard: skip if aliases already present from a previous run
+		if grep -q '# Claude Code environment and aliases' "$rc" 2>/dev/null; then
+			echo "[setup-aliases] Aliases already present in $(basename $rc), skipping"
+			continue
+		fi
+		echo "" >>"$rc"
+		echo "# Claude Code environment and aliases (managed by setup-aliases.sh)" >>"$rc"
+		# Export CLAUDE_CONFIG_DIR so it's available in all shells (not just VS Code remoteEnv)
+		if ! grep -q 'export CLAUDE_CONFIG_DIR=' "$rc" 2>/dev/null; then
+			echo "export CLAUDE_CONFIG_DIR=\"${CLAUDE_CONFIG_DIR}\"" >>"$rc"
+		fi
+		# Export UTF-8 locale so tmux renders Unicode correctly (docker exec doesn't inherit locale)
+		if ! grep -q 'export LANG=en_US.UTF-8' "$rc" 2>/dev/null; then
+			echo 'export LANG=en_US.UTF-8' >>"$rc"
+			echo 'export LC_ALL=en_US.UTF-8' >>"$rc"
+		fi
+		# Prefer native binary over npm-installed version
+		# 'claude install' puts the binary at ~/.local/bin/claude
+		# Legacy manual installs used /usr/local/bin/claude — check both
+		cat >>"$rc" <<'CLAUDEBIN_EOF'
+if [ -x "$HOME/.local/bin/claude" ]; then
+    _CLAUDE_BIN="$HOME/.local/bin/claude"
+elif [ -x /usr/local/bin/claude ]; then
+    _CLAUDE_BIN=/usr/local/bin/claude
+else
+    _CLAUDE_BIN=claude
+fi
+CLAUDEBIN_EOF
+		echo "$ALIAS_CC" >>"$rc"
+		echo "$ALIAS_CLAUDE" >>"$rc"
+		echo "$ALIAS_CCRAW" >>"$rc"
 
-        # --- Add environment and aliases (idempotent) ---
-        # Guard: skip if aliases already present from a previous run
-        if grep -q '# Claude Code environment and aliases' "$rc" 2>/dev/null; then
-            echo "[setup-aliases] Aliases already present in $(basename $rc), skipping"
-            continue
-        fi
-        echo "" >> "$rc"
-        echo "# Claude Code environment and aliases (managed by setup-aliases.sh)" >> "$rc"
-        # Export CLAUDE_CONFIG_DIR so it's available in all shells (not just VS Code remoteEnv)
-        if ! grep -q 'export CLAUDE_CONFIG_DIR=' "$rc" 2>/dev/null; then
-            echo "export CLAUDE_CONFIG_DIR=\"${CLAUDE_CONFIG_DIR}\"" >> "$rc"
-        fi
-        # Export UTF-8 locale so tmux renders Unicode correctly (docker exec doesn't inherit locale)
-        if ! grep -q 'export LANG=en_US.UTF-8' "$rc" 2>/dev/null; then
-            echo 'export LANG=en_US.UTF-8' >> "$rc"
-            echo 'export LC_ALL=en_US.UTF-8' >> "$rc"
-        fi
-        echo "$ALIAS_CC" >> "$rc"
-        echo "$ALIAS_CLAUDE" >> "$rc"
-        echo "$ALIAS_CCRAW" >> "$rc"
-
-        # cc-tools: list all available CodeForge tools with version info
-        cat >> "$rc" << 'CCTOOLS_EOF'
+		# cc-tools: list all available CodeForge tools with version info
+		cat >>"$rc" <<'CCTOOLS_EOF'
 cc-tools() {
   echo "CodeForge Available Tools"
   echo "━━━━━━━━━━━━━━━━━━━━━━━━"
@@ -101,12 +113,12 @@ cc-tools() {
 }
 CCTOOLS_EOF
 
-        # check-setup: alias to the health check script
-        DEVCONTAINER_SCRIPTS="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-        echo "alias check-setup='bash ${DEVCONTAINER_SCRIPTS}/check-setup.sh'" >> "$rc"
+		# check-setup: alias to the health check script
+		DEVCONTAINER_SCRIPTS="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+		echo "alias check-setup='bash ${DEVCONTAINER_SCRIPTS}/check-setup.sh'" >>"$rc"
 
-        echo "[setup-aliases] Added aliases to $(basename $rc)"
-    fi
+		echo "[setup-aliases] Added aliases to $(basename $rc)"
+	fi
 done
 
 echo "[setup-aliases] Aliases configured:"