cortexhawk 3.1.0 → 3.2.0

package/CHANGELOG.md

@@ -3,6 +3,33 @@
 All notable changes to CortexHawk are documented here.
 Format: [Keep a Changelog](https://keepachangelog.com/)
 
+## [3.2.0] - 2026-02-15
+
+### Added
+- `/commit` command: lightweight conventional commit + push without review or PR — use `/ship` for full workflow, `/commit` for quick iterations
+- Install auto-detects existing PR/commit templates; generates CortexHawk defaults (`.github/PULL_REQUEST_TEMPLATE.md`, `.gitmessage`) if missing — agents (`git-manager`, `/ship`, `/commit`) read templates at runtime
+- `--version` / `-v` flag: displays CortexHawk version
+- `scripts/refresh-context.sh`: regenerates `docs/.context/_shared.md` mid-session — `/task` and `/backlog` auto-refresh after modifying backlog
+
+### Fixed
+- `branch-guard` / `commit-guard` hooks: JSON parsing via `jq` with regex fallback — fixes false "hook error" on commands containing quotes or HEREDOC
+- `commit-guard`: multi-format commit message extraction (HEREDOC, single/double quotes)
+- `file-guard`: match on basename only — `*secret*`/`*credentials*` no longer false-positive on legitimate files (e.g., `oauth_service.py`); `.env.example`/`.env.sample`/`.env.template` whitelisted; `docker-compose*.yml` unblocked
+- **Security**: eliminate shell injection in all Python HEREDOC/inline scripts — `$hooks_json`, file paths, and user input no longer interpolated into Python source; uses `sys.argv`/`sys.stdin` instead. Hook names validated against path traversal, hook paths shell-escaped via `shlex.quote()`
+- Portable `sed -i` via `sed_inplace()` helper — fixes `sed` failures on macOS (BSD) across snapshot, hook toggle, and init wizard
+- Argument validation for `--target`, `--profile`, and `--restore` flags — prevents cryptic shell errors when value is missing
+- `update_gitignore()` now ensures essential entries (`.env`, `node_modules/`, `dist/`, etc.) are present — previously only added `.claude/` to an existing `.gitignore`
+- Warning when python3 is not found — `generate_hooks_config()` previously failed silently, now alerts user that static fallback is used
+- `.env` parser now strips single quotes, inline comments, and trailing whitespace — previously only stripped double quotes
+- `--init` wizard now supports "All" and "Auto-detect" targets — removed false `--target all/auto` + `--init` guards, scope step auto-selects local for multi-target
+- Snapshot no longer reads stale `/tmp/cortexhawk-custom-*.json` from previous runs — uses `$PROFILE_FILE` from current session only
+- `copy_skills()` now warns when a skill from the profile doesn't exist in source — previously silently skipped
+- Removed `local` keyword used outside function in `--target auto` dispatcher — fixes portability issues
+- `.gitignore` no longer duplicates `# CortexHawk` header with `--target all` — groups all target dirs under single header
+- `SKILL_COUNT` no longer shows 1 when no skills detected — fixed `wc -l` on empty string in `autodetect-profile.sh`
+- `_shared.md` now includes generation timestamp for staleness awareness
+- `settings.json` now merges on reinstall instead of skipping — new hooks regenerated from compose.yml, new permissions added via union (user customizations preserved). `--update` also merges new permissions
+
 ## [3.1.0] - 2026-02-14
 
 ### Added
@@ -11,6 +38,9 @@ Format: [Keep a Changelog](https://keepachangelog.com/)
 - `--target auto`: auto-detects installed CLIs (claude, kimi, codex) and installs for all found — no need to specify which CLIs are available
 - `cortexhawk validate [path]`: post-install diagnostic that verifies skills/agents/commands/hooks discovery per target — checks manifest, file counts, settings.json validity, .gitignore coverage
 - npm distribution: `npm install -g cortexhawk` installs the CLI globally — auto-resolves `CORTEXHAWK_HOME` from symlinked binary, `self-update` detects npm install and suggests `npm update -g`
+- `/pulse --unused`: detects installed skills that don't match the project's tech stack — scans for technology markers, maps framework skills to stacks, reports potentially unused skills
+- `/chain --browse`: lists all available chain presets (built-in + custom from `.cortexhawk-chains.yml`) and recent chain runs from `docs/chains/`
+- `cortexhawk sync [path] [from]`: syncs modified skills across installed CLI targets — compares checksums, copies changed skills, skips generated content (cmd-*, hook-*, agent-*)
 
 ## [3.0.0] - 2026-02-14
 

package/CLAUDE.md

@@ -6,7 +6,7 @@ Open-source development toolkit for Claude Code — optimized agents, skills, co
 
 ```
 agents/       — 20 specialized AI agents
-commands/     — 32 slash commands
+commands/     — 33 slash commands
 scripts/      — Validation and post-install audit scripts
 skills/       — 36 domain-specific knowledge modules
 hooks/        — 9 lifecycle hooks
@@ -49,7 +49,7 @@ Custom agents in `.cortexhawk-agents/` at project root. Each `.md` file uses `ex
 
 ## Commands
 
-`/plan` `/build` `/test` `/review` `/ship` `/debug` `/scan` `/check` `/refactor` `/research` `/doc` `/bootstrap` `/tdd` `/optimize` `/migrate` `/monitor` `/api-gen` `/changelog` `/journal` `/brainstorm` `/simplify` `/deploy` `/export` `/backlog` `/pulse` `/map` `/learn` `/chain` `/task` `/ci` `/context` `/upgrade`
+`/plan` `/build` `/test` `/review` `/ship` `/commit` `/debug` `/scan` `/check` `/refactor` `/research` `/doc` `/bootstrap` `/tdd` `/optimize` `/migrate` `/monitor` `/api-gen` `/changelog` `/journal` `/brainstorm` `/simplify` `/deploy` `/export` `/backlog` `/pulse` `/map` `/learn` `/chain` `/task` `/ci` `/context` `/upgrade`
 
 ## Skills
 

package/README.md

@@ -2,27 +2,50 @@
 
 [![GitHub stars](https://img.shields.io/github/stars/Spechawk94/CortexHawk?style=flat-square)](https://github.com/Spechawk94/CortexHawk/stargazers)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square)](LICENSE)
-[![Version](https://img.shields.io/badge/version-3.0.0-green.svg?style=flat-square)](CHANGELOG.md)
+[![Version](https://img.shields.io/badge/version-3.2.0-green.svg?style=flat-square)](CHANGELOG.md)
+[![npm](https://img.shields.io/npm/v/cortexhawk?style=flat-square&color=red)](https://www.npmjs.com/package/cortexhawk)
 [![Skills](https://img.shields.io/badge/skills-36%20built--in%20%7C%2087k%2B%20via%20SkillsMP-orange.svg?style=flat-square)](https://skillsmp.com)
-[![Components](https://img.shields.io/badge/20%20agents%20%7C%2032%20commands%20%7C%209%20hooks%20%7C%207%20modes-purple.svg?style=flat-square)](#whats-inside)
+[![Components](https://img.shields.io/badge/20%20agents%20%7C%2033%20commands%20%7C%209%20hooks%20%7C%207%20modes-purple.svg?style=flat-square)](#whats-inside)
 
 An open-source, community-driven development toolkit for Claude Code.
 
 CortexHawk provides a modular collection of optimized agents, skills, commands, hooks, and behavioral modes that transform Claude Code into a full-stack development team. Every prompt has been written for maximum efficiency — less token bloat, sharper instructions, better agent coordination.
 
-### What's New in v3.0
+### What's New in v3.2
+
+- **`/commit` command** — lightweight conventional commit + push without review or PR (use `/ship` for full workflow)
+- **`--version` flag** — standard CLI version display
+- **PR/commit templates** — auto-detected at install, generated if missing; agents read templates at runtime
+- **Settings.json merge** — reinstall and `--update` now merge new hooks + permissions instead of skipping
+- **Security hardening** — eliminated shell injection in all Python HEREDOC scripts, portable `sed -i`, input validation
+- **`--init` wizard** — "Auto-detect" target option, improved multi-target support
+- **15+ bug fixes** — see [CHANGELOG.md](CHANGELOG.md) for full details
+
+<details>
+<summary>v3.1 changes</summary>
+
+- **`npm install -g cortexhawk`** — available on npm, auto-resolves source from symlinked binary
+- **`cortexhawk` CLI wrapper** — clean subcommands (init, install, update, doctor, validate, search, snapshot, etc.) instead of `bash install.sh --flags`
+- **`--target auto`** — auto-detects installed CLIs (claude, kimi, codex) and installs for all found
+- **`cortexhawk validate`** — post-install diagnostic verifying skills/agents discovery per target
+
+</details>
+
+<details>
+<summary>v3.0 changes</summary>
 
 - **`--init` wizard overhaul** — reordered flow with git workflow config, auto `git init` + `.gitignore` creation, branching strategies (direct-main, dev-branch, git-flow)
 - **`/bootstrap --smart`** — researcher agent scans roadmap, compares stacks, recommends, then scaffolds
 - **Post-install gitignore** — auto-adds `.claude/`, `.kimi/`, `.codex/` to `.gitignore`, asks about `docs/`
 - **`--update` checksum detection** — compares file checksums instead of just version numbers to detect changes
 - **Kimi CLI overhaul** — agents, commands, hooks all converted to skills; AGENTS.md at project root; MCP optional; auto `.envrc` for local install
-- **Codex CLI fixes** — config.toml format fixes (flat model key, save-all persistence)
 - **`--demo` flag** — sandbox project in `/tmp/` with intentional bugs for testing
 - **`/upgrade` command** — check for updates, show changelog diff, propose `--update`
 - **`--publish-skill`** — publish local skills to GitHub with auto-generated README
 - **Cursor CLI removed** — too unstable for maintained support
 
+</details>
+
 ## Quick Start
 
 ```bash
@@ -93,7 +116,7 @@ Specialized AI agents that coordinate together instead of working in silos.
 | `fullstack-developer` | Full-stack orchestration front+back |
 | `teacher` | Teaches concepts with 3 pedagogical levels (guided, mentor, professor) |
 
-### Commands (32)
+### Commands (33)
 
 Slash commands for common workflows.
 
@@ -104,6 +127,7 @@ Slash commands for common workflows.
 | `/test` | Generate and run tests |
 | `/review` | Multi-agent code review |
 | `/ship` | Commit + PR pipeline |
+| `/commit` | Lightweight commit + push (no review, no PR) |
 | `/debug` | Debug and fix issues |
 | `/scan` | Full security audit |
 | `/check` | Pre-commit quality gate (lint + test + scan + review → GO/NO-GO) |
@@ -303,7 +327,7 @@ Each target adapts components to the CLI's native format:
 | Component | Claude Code | Kimi CLI | Codex CLI |
 |---|---|---|---|
 | Agents (20) | `.claude/agents/*.md` | Skills (`/skill:agent-*`) + `AGENTS.md` | `AGENTS.md` |
-| Commands (32) | `.claude/commands/*.md` → `/plan` | Skills (`/skill:cmd-*`) | Skills (`$cmd-*`) |
+| Commands (33) | `.claude/commands/*.md` → `/plan` | Skills (`/skill:cmd-*`) | Skills (`$cmd-*`) |
 | Skills (36) | `.claude/skills/` | `.kimi/skills/` (auto-discovered) | `.agents/skills/` |
 | Hooks (9) | `settings.json` (automatic) | Skills (`/skill:hook-*`, manual) | Dispatcher (partial) |
 | Modes (7) | `.claude/modes/` (native) | Skills (`/skill:modes/*`) | Skills (`$mode-*`) |
@@ -325,6 +349,7 @@ Each target adapts components to the CLI's native format:
 ./install.sh --update --dry-run        # preview update delta
 
 # Diagnostics
+./install.sh --version                 # show CortexHawk version
 ./install.sh --doctor                  # check installation health
 ./install.sh --test-hooks              # dry-run all hooks with synthetic inputs
 ./install.sh --stats                   # installation overview (version, counts)

package/agents/git-manager.md

@@ -49,6 +49,10 @@ Description: imperative mood, lowercase, no period, max 72 chars
 - Checklist: tests pass, no warnings, docs updated
 ```
 
+## Templates
+- Before creating a PR, check for `.github/PULL_REQUEST_TEMPLATE.md` — if found, follow that format
+- Before committing, check for `.gitmessage` — if found, follow that format for the commit message
+
 ## Rules
 - Atomic commits — one logical change per commit
 - Never force-push to shared branches

package/commands/backlog.md

@@ -12,6 +12,7 @@ Activate the **project-manager** agent in backlog mode.
 3. Score: impact (H/M/L), effort (H/M/L), feasibility (H/M/L)
 4. Update `docs/backlog.md` — add new items, re-prioritize existing ones
 5. Mark items already implemented as done
+6. Run `bash scripts/refresh-context.sh` to update shared context
 
 Backlog format in `docs/backlog.md`:
 

package/commands/chain.md

@@ -11,7 +11,7 @@ Execute a declared sequence of agents with automatic context passing. Topic: `$A
 
 **Custom presets**: Define in `.cortexhawk-chains.yml` at project root — custom presets override built-in presets with the same name
 
-**Flags**: `--gate` = pause between steps | `--copy` = physical copy to plans/ | `--replay <slug>` = re-run a previous chain
+**Flags**: `--gate` = pause between steps | `--copy` = physical copy to plans/ | `--replay <slug>` = re-run a previous chain | `--browse` = list all available presets + recent chains
 
 **Mapping**: plan=planner, build=implementer, test=tester, review=reviewer, scan=security-auditor, debug=debugger, doc=docs-manager, ship=git-manager, refactor=code-simplifier, research=researcher
 
@@ -38,6 +38,15 @@ When detected in a step's output:
 2. Save as `{N}a-{delegated-agent}.md` (sub-step)
 3. Feed original output + delegation result to the next step
 
+## Browse mode (`--browse`)
+
+List all available chains from 3 sources:
+1. **Built-in presets** — default, security, ship (table: name, sequence, description)
+2. **Custom presets** — read `.cortexhawk-chains.yml` if present (table: name, sequence, description, gate)
+3. **Recent chains** — scan `docs/chains/*/SUMMARY.md`, extract date/slug/sequence/result (table: date, slug, sequence, status — last 10)
+
+Output all 3 tables. End with usage hint: `/chain <preset> <topic>`
+
 ## Rules
 
 - Max 8 agents per chain (delegations count toward this limit)

package/commands/commit.md

@@ -0,0 +1,24 @@
+---
+name: commit
+description: Conventional commit and push — lightweight alternative to /ship (no review, no PR).
+---
+
+# /commit
+
+Activate the **git-manager** agent. Commit: `$ARGUMENTS`
+
+1. Read `## Git Workflow` from CLAUDE.md if present — respect branching strategy, commit convention, and auto-push settings
+2. If `.gitmessage` exists, read it for commit message format guidance
+3. Review staged and unstaged changes, stage relevant files (never `git add -A`)
+4. Generate conventional commit message from changes — format: `type(scope): description`
+5. Commit with the generated message
+6. If auto-push is enabled, push to remote
+7. Show commit summary (hash, message, files changed)
+
+## Rules
+
+- No review pass — use `/ship` for reviewed commits, `/commit` for quick iterations
+- No PR creation — use `/ship` when a PR is needed
+- Respect `.gitignore` — never stage `.env`, secrets, or debug artifacts
+- If no changes to commit, report and stop
+- If `$ARGUMENTS` is provided, use it as commit message context (not the literal message)

package/commands/pulse.md

@@ -7,7 +7,7 @@ description: Project health dashboard — code quality metrics at a glance.
 
 Activate the **project-manager** agent in health-check mode. Scope: `$ARGUMENTS`
 
-**Flags**: `--history Nd` = show metrics trends over N days (e.g., `--history 7d`, `--history 30d`)
+**Flags**: `--history Nd` = show metrics trends over N days | `--unused` = detect potentially unused skills
 
 ## Standard mode (no flag)
 
@@ -44,3 +44,13 @@ Avg: [tokens/day] tokens/day, [duration] min/session
 ```
 
 If scope is specified, limit checks to those files/directories.
+
+## Unused skills mode (`--unused`)
+
+Detect installed skills that don't match the project's tech stack.
+
+1. **List installed skills** from `.claude/skills/` (or target equivalent)
+2. **Detect stack** — scan for: `package.json`/`*.ts` → js/ts, `requirements.txt`/`*.py` → python, `go.mod` → go, `Cargo.toml` → rust, `Dockerfile` → docker, `*.svelte` → svelte, `next.config.*` → nextjs, `tailwind.config.*` → tailwind
+3. **Map framework skills** — `frameworks/react` → js, `frameworks/nextjs` → nextjs, `frameworks/sveltekit` → svelte, `frameworks/fastapi` → python, `frameworks/python` → python, `frameworks/typescript` → ts, `frameworks/tailwindcss` → tailwind, `devops/docker` → docker
+4. **Universal skills** (security/\*, quality/\*, testing/\*, meta/\*, databases/\*, workflow/\*, optimization/\*) → always relevant, skip
+5. **Output** — table with skill, required stack, OK/UNUSED status. Count unused. Suggest `cortexhawk install --profile autodetect`

package/commands/ship.md

@@ -11,7 +11,7 @@ Activate the **git-manager** agent, then the **reviewer** agent. Ship: `$ARGUMEN
 1. Stage changes and generate conventional commit message
 2. Run quick review pass — reviewer runs Pass 1 (Correctness) and Pass 2 (Security) only, reporting Critical findings exclusively
 3. If review passes, commit and push
-4. Create PR with description, testing notes, and checklist
+4. Create PR — if `.github/PULL_REQUEST_TEMPLATE.md` exists, follow that format; otherwise use: Summary, Changes, Test Plan, Checklist
 5. If review finds critical issues, report them and stop — don't ship broken code
 
 Format: `feat(scope): description` or `fix(scope): description`

package/commands/task.md

@@ -16,6 +16,7 @@ Activate the **project-manager** agent as orchestrator. Execute backlog item `$A
 6. Update `CHANGELOG.md` with a one-line entry under the current version's `### Added` section
 7. If chain completes without critical blockers, execute `/ship`
 8. Mark item as `done` in backlog
+9. Run `bash scripts/refresh-context.sh` to update shared context
 
 ## Save Rules
 

package/cortexhawk

@@ -250,6 +250,91 @@ do_validate() {
     fi
 }
 
+# --- sync command ---
+do_sync() {
+    local project_root="${1:-.}"
+    local from_target="${2:-}"
+
+    # Detect installed targets
+    local targets=()
+    [ -f "$project_root/.claude/.cortexhawk-manifest" ] && targets+=("claude")
+    [ -f "$project_root/.kimi/.cortexhawk-manifest" ] && targets+=("kimi")
+    [ -f "$project_root/.codex/.cortexhawk-manifest" ] && targets+=("codex")
+
+    if [ "${#targets[@]}" -lt 2 ]; then
+        yellow "Sync requires at least 2 targets installed. Found: ${targets[*]:-none}"
+        exit 1
+    fi
+
+    # Determine source target
+    if [ -z "$from_target" ]; then
+        from_target="${targets[0]}"
+    fi
+
+    # Map target to skills directory
+    target_skills_dir() {
+        case "$1" in
+            claude) echo "$project_root/.claude/skills" ;;
+            kimi)   echo "$project_root/.kimi/skills" ;;
+            codex)  echo "$project_root/.agents/skills" ;;
+        esac
+    }
+
+    local src_dir
+    src_dir=$(target_skills_dir "$from_target")
+    if [ ! -d "$src_dir" ]; then
+        red "Source skills dir not found: $src_dir"
+        exit 1
+    fi
+
+    echo "CortexHawk Sync"
+    echo "==============="
+    echo "  Source: $from_target ($src_dir)"
+    echo "  Targets: ${targets[*]}"
+    echo ""
+
+    local synced=0
+    for target in "${targets[@]}"; do
+        [ "$target" = "$from_target" ] && continue
+        local dst_dir
+        dst_dir=$(target_skills_dir "$target")
+        [ ! -d "$dst_dir" ] && continue
+
+        # Sync each skill category/name
+        for skill_file in "$src_dir"/*/SKILL.md "$src_dir"/*/*/SKILL.md; do
+            [ ! -f "$skill_file" ] && continue
+            local rel_path="${skill_file#"$src_dir/"}"
+            local dst_file="$dst_dir/$rel_path"
+
+            # Skip generated skills (cmd-*, hook-*, agent-*, modes/)
+            case "$rel_path" in
+                cmd-*|hook-*|agent-*|modes/*) continue ;;
+            esac
+
+            # Compare checksums
+            if [ -f "$dst_file" ]; then
+                local src_md5 dst_md5
+                src_md5=$(md5sum "$skill_file" 2>/dev/null | cut -d' ' -f1)
+                dst_md5=$(md5sum "$dst_file" 2>/dev/null | cut -d' ' -f1)
+                [ "$src_md5" = "$dst_md5" ] && continue
+            fi
+
+            # Copy
+            mkdir -p "$(dirname "$dst_file")"
+            cp "$skill_file" "$dst_file"
+            echo "  [SYNC] $rel_path → $target"
+            synced=$((synced + 1))
+        done
+    done
+
+    echo ""
+    if [ "$synced" -eq 0 ]; then
+        green "All targets already in sync."
+    else
+        green "Synced $synced file(s)."
+    fi
+}
+
 # Verify CortexHawk source exists
 check_home() {
     if [ ! -f "$INSTALL_SH" ]; then
@@ -276,6 +361,7 @@ show_help() {
     echo ""
     echo "Diagnostics:"
     echo "  validate [path]     Verify skills/agents discovery per target"
+    echo "  sync [path] [from]  Sync skills across installed CLI targets"
     echo "  doctor              Check installation health"
     echo "  stats               Show installation overview"
     echo "  quickstart          Getting-started guide"
@@ -336,6 +422,10 @@ case "$cmd" in
         shift
         do_validate "$@"
         ;;
+    sync)
+        shift
+        do_sync "$@"
+        ;;
     doctor)
         check_home
         shift

package/hooks/branch-guard.sh

@@ -7,7 +7,12 @@ if [ -n "$CORTEXHAWK_COMMAND" ]; then
   CMD="$CORTEXHAWK_COMMAND"
 else
   INPUT=$(cat)
-  CMD=$(printf '%s' "$INPUT" | grep -o '"command" *: *"[^"]*"' | head -1 | sed 's/.*: *"//;s/"$//')
+  if command -v jq &>/dev/null; then
+    CMD=$(printf '%s' "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null)
+  fi
+  if [[ -z "$CMD" ]]; then
+    CMD=$(printf '%s' "$INPUT" | grep -o '"command" *: *"[^"]*"' | head -1 | sed 's/.*: *"//;s/"$//')
+  fi
 fi
 
 if [[ -z "$CMD" ]]; then

package/hooks/commit-guard.sh

@@ -7,7 +7,12 @@ if [ -n "$CORTEXHAWK_COMMAND" ]; then
   CMD="$CORTEXHAWK_COMMAND"
 else
   INPUT=$(cat)
-  CMD=$(printf '%s' "$INPUT" | grep -o '"command" *: *"[^"]*"' | head -1 | sed 's/.*: *"//;s/"$//')
+  if command -v jq &>/dev/null; then
+    CMD=$(printf '%s' "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null)
+  fi
+  if [[ -z "$CMD" ]]; then
+    CMD=$(printf '%s' "$INPUT" | grep -o '"command" *: *"[^"]*"' | head -1 | sed 's/.*: *"//;s/"$//')
+  fi
 fi
 
 if [[ -z "$CMD" ]]; then
@@ -20,9 +25,17 @@ if ! echo "$CMD" | grep -qE 'git\s+commit'; then
 fi
 
 # Extract commit message from -m flag
-COMMIT_MSG=$(echo "$CMD" | grep -oP '(?<=-m\s["\x27]).*?(?=["\x27])' 2>/dev/null)
+# Handle: -m "msg", -m 'msg', -m "$(cat <<'EOF'\nmsg\nEOF\n)"
+COMMIT_MSG=$(echo "$CMD" | sed -n 's/.*-m[[:space:]]*"\$(cat <<.*//p' 2>/dev/null)
+if [[ -n "$COMMIT_MSG" ]]; then
+  # HEREDOC style — extract first non-empty line after the heredoc opener
+  COMMIT_MSG=$(echo "$CMD" | sed -n '/cat <</{n;p;}' | sed 's/^[[:space:]]*//' 2>/dev/null)
+fi
+if [[ -z "$COMMIT_MSG" ]]; then
+  COMMIT_MSG=$(echo "$CMD" | grep -oP "(?<=-m\s[\"'])(.+?)(?=[\"'](\s|$))" 2>/dev/null | head -1)
+fi
 if [[ -z "$COMMIT_MSG" ]]; then
-  COMMIT_MSG=$(echo "$CMD" | grep -oP '(?<=-m\s)(\S+)' 2>/dev/null)
+  COMMIT_MSG=$(echo "$CMD" | grep -oP '(?<=-m\s)\S+' 2>/dev/null | head -1)
 fi
 
 # Load git workflow config — skip conventional check if freeform

package/hooks/file-guard.sh

@@ -2,20 +2,28 @@
 # file-guard — Blocks Claude from accessing sensitive files
 # Hook type: PreToolUse (Read|Edit|Write)
 
+# Patterns matched against BASENAME only
 BLOCKED_PATTERNS=(
   ".env"
-  ".env.*"
   "*.pem"
   "*.key"
-  "*credentials*"
-  "*secret*"
   "id_rsa"
   "id_ed25519"
-  ".ssh/*"
   "*.p12"
   "*.pfx"
   "*.keystore"
-  "docker-compose*.yml"
+  "credentials.json"
+  "credentials.yml"
+  "credentials.yaml"
+)
+
+# Basename patterns that are .env.* but NOT .env.example/.env.sample/.env.template
+BLOCKED_ENV_GLOB=".env.*"
+ALLOWED_ENV_NAMES=(".env.example" ".env.sample" ".env.template")
+
+# Path patterns — only match directory components
+BLOCKED_PATH_PATTERNS=(
+  ".ssh/"
 )
 
 # Read file_path from stdin JSON (Claude Code hook protocol)
@@ -42,10 +50,35 @@ BASENAME=$(basename "$RESOLVED")
 # Also check against the full resolved path
 RELPATH="$RESOLVED"
 
+# Check basename against exact patterns
 for pattern in "${BLOCKED_PATTERNS[@]}"; do
-  if [[ "$BASENAME" == $pattern ]] || [[ "$RELPATH" == *$pattern ]]; then
+  if [[ "$BASENAME" == $pattern ]]; then
+    echo "BLOCKED: Access to '$FILE_ARG' denied by file-guard" >&2
+    echo "Matched pattern: '$pattern'" >&2
+    exit 2
+  fi
+done
+
+# Check .env.* files (allow .env.example/.env.sample/.env.template)
+if [[ "$BASENAME" == $BLOCKED_ENV_GLOB ]]; then
+  ALLOWED=false
+  for name in "${ALLOWED_ENV_NAMES[@]}"; do
+    if [[ "$BASENAME" == "$name" ]]; then
+      ALLOWED=true
+      break
+    fi
+  done
+  if [[ "$ALLOWED" == false ]]; then
+    echo "BLOCKED: Access to '$FILE_ARG' denied by file-guard" >&2
+    echo "Matched pattern: '$BLOCKED_ENV_GLOB'" >&2
+    exit 2
+  fi
+fi
+
+# Check path patterns (directory components)
+for pattern in "${BLOCKED_PATH_PATTERNS[@]}"; do
+  if [[ "$RELPATH" == *"$pattern"* ]]; then
     echo "BLOCKED: Access to '$FILE_ARG' denied by file-guard" >&2
-    echo "Resolved path: $RESOLVED" >&2
     echo "Matched pattern: '$pattern'" >&2
     exit 2
   fi

package/hooks/session-start.sh

@@ -44,14 +44,17 @@ if [ -d "docs/.context" ] && [ ! -L "docs/.context" ]; then
 
     echo "# Shared Context" > "$SHARED"
     echo "" >> "$SHARED"
-    echo "_Auto-generated by session-start. Do not edit manually._" >> "$SHARED"
+    echo "_Auto-generated at $(date '+%Y-%m-%d %H:%M'). Snapshot from session start — may be stale._" >> "$SHARED"
     echo "" >> "$SHARED"
 
     # Backlog summary
     if [ -f "docs/backlog.md" ]; then
-        ACTIVE=$(grep -c '| todo |' docs/backlog.md 2>/dev/null || echo 0)
-        DEFERRED=$(grep -c '| deferred |' docs/backlog.md 2>/dev/null || echo 0)
-        DONE=$(grep -c '| done |' docs/backlog.md 2>/dev/null || echo 0)
+        ACTIVE=$(grep -c '| todo |' docs/backlog.md 2>/dev/null || true)
+        : "${ACTIVE:=0}"
+        DEFERRED=$(grep -c '| deferred |' docs/backlog.md 2>/dev/null || true)
+        : "${DEFERRED:=0}"
+        DONE=$(grep -c '| done |' docs/backlog.md 2>/dev/null || true)
+        : "${DONE:=0}"
         echo "## Backlog" >> "$SHARED"
         echo "- Active: $ACTIVE | Deferred: $DEFERRED | Done: $DONE" >> "$SHARED"
         # List active items

package/install.sh

@@ -7,7 +7,14 @@ SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 if [ -f ".env" ]; then
     while IFS='=' read -r key value; do
         [[ -z "$key" || "$key" == \#* ]] && continue
+        # Strip double quotes
         value="${value%\"}" && value="${value#\"}"
+        # Strip single quotes
+        value="${value%'}" && value="${value#'}"
+        # Strip inline comments (space + # marks start of comment)
+        value="$(printf '%s\n' "$value" | sed 's/[[:space:]]#.*$//')"
+        # Strip trailing whitespace
+        value="${value%"${value##*[! ]}"}"
         export "$key=$value" 2>/dev/null || true
     done < .env
 fi
@@ -20,6 +27,15 @@ get_version() {
     grep -m1 '## \[' "$SCRIPT_DIR/CHANGELOG.md" | sed 's/.*\[\([^]]*\)\].*/\1/'
 }
 
+# Portable sed -i (GNU vs BSD)
+sed_inplace() {
+    if sed --version 2>/dev/null | grep -q GNU; then
+        sed -i "$@"
+    else
+        sed -i '' "$@"
+    fi
+}
+
 compute_checksum() {
     local file="$1"
     if command -v sha256sum >/dev/null 2>&1; then
@@ -106,6 +122,7 @@ print_usage() {
     echo "  --dry-run         Simulate install/update without writing files"
     echo "  --test-hooks      Dry-run all hooks with synthetic inputs"
     echo "  --no-scan         Skip post-install security audit"
+    echo "  --version, -v     Show CortexHawk version"
     echo "  --help, -h        Show this help"
 }
 
@@ -149,10 +166,18 @@ MAX_SNAPSHOTS=10
 while [ $# -gt 0 ]; do
     case "$1" in
         --target)
+            if [ -z "${2:-}" ]; then
+                echo "Error: --target requires a value (claude|kimi|codex|auto|all)"
+                exit 1
+            fi
             TARGET_CLI="$2"
             shift 2
             ;;
         --profile)
+            if [ -z "${2:-}" ]; then
+                echo "Error: --profile requires a value (fullstack|api|data)"
+                exit 1
+            fi
             PROFILE="$2"
             shift 2
             ;;
@@ -218,6 +243,10 @@ while [ $# -gt 0 ]; do
             ;;
         --restore)
             RESTORE_MODE=true
+            if [ -z "${2:-}" ]; then
+                echo "Error: --restore requires a snapshot path or --latest"
+                exit 1
+            fi
             SNAPSHOT_FILE="$2"
             if [ "$SNAPSHOT_FILE" = "--latest" ]; then
                 if [ "$GLOBAL" = true ]; then
@@ -323,6 +352,10 @@ while [ $# -gt 0 ]; do
             fi
             shift 2
             ;;
+        --version|-v)
+            echo "CortexHawk $(get_version)"
+            exit 0
+            ;;
         --help|-h)
             print_usage
             exit 0
@@ -368,14 +401,6 @@ if [ "$RESTORE_MODE" = true ] && { [ "$INIT_MODE" = true ] || [ "$UPDATE_MODE" =
     echo "Error: --restore cannot be combined with --init or --update"
     exit 1
 fi
-if [ "$TARGET_CLI" = "all" ] && [ "$INIT_MODE" = true ]; then
-    echo "Error: --target all cannot be combined with --init (run --init per target instead)"
-    exit 1
-fi
-if [ "$TARGET_CLI" = "auto" ] && [ "$INIT_MODE" = true ]; then
-    echo "Error: --target auto cannot be combined with --init (run --init per target instead)"
-    exit 1
-fi
 if [ -n "$ADD_SKILL_URL" ] && { [ "$INIT_MODE" = true ] || [ "$UPDATE_MODE" = true ] || [ "$SNAPSHOT_MODE" = true ] || [ "$RESTORE_MODE" = true ]; }; then
     echo "Error: --add-skill cannot be combined with --init, --update, --snapshot, or --restore"
     exit 1
@@ -486,6 +511,10 @@ copy_skills() {
         grep '"[a-z]' "$PROFILE_FILE" | sed 's/.*"\([a-z][^"]*\)".*/\1/' | grep '/' | while read -r skill; do
             local src="$SCRIPT_DIR/skills/$skill"
             local dest="$target_dir/skills/$skill"
+            if [ ! -d "$src" ]; then
+                yellow "  Warning: skill '$skill' not found in source — skipping"
+                continue
+            fi
             mkdir -p "$(dirname "$dest")"
             cp -r "$src" "$dest" 2>/dev/null || true
         done
@@ -594,11 +623,34 @@ update_gitignore() {
         touch "$gitignore"
     fi
 
-    # Auto-add target directory (always)
-    if ! grep -qx "$target_dir/" "$gitignore" 2>/dev/null; then
-        echo "" >> "$gitignore"
-        echo "# CortexHawk" >> "$gitignore"
-        echo "$target_dir/" >> "$gitignore"
+    # Ensure essential entries are present (disable glob to keep *.log literal)
+    local essentials="node_modules/ __pycache__/ .env .env.local *.log dist/ build/ .DS_Store"
+    local added_count=0
+    set -f
+    for entry in $essentials; do
+        if ! grep -qxF "$entry" "$gitignore" 2>/dev/null; then
+            echo "$entry" >> "$gitignore"
+            added_count=$((added_count + 1))
+        fi
+    done
+    set +f
+    if [ "$added_count" -gt 0 ]; then
+        green "  Added $added_count essential entries to .gitignore (.env, node_modules/, etc.)"
+    fi
+
+    # Auto-add target directory (always), group under single header
+    if ! grep -qxF "$target_dir/" "$gitignore" 2>/dev/null; then
+        if grep -q "# CortexHawk" "$gitignore" 2>/dev/null; then
+            # Append under the first existing header only
+            local header_line
+            header_line=$(grep -n "# CortexHawk" "$gitignore" | head -1 | cut -d: -f1)
+            sed_inplace "${header_line}a\\
+$target_dir/" "$gitignore"
+        else
+            echo "" >> "$gitignore"
+            echo "# CortexHawk" >> "$gitignore"
+            echo "$target_dir/" >> "$gitignore"
+        fi
         green "  Added $target_dir/ to .gitignore"
     fi
 
@@ -619,6 +671,52 @@ update_gitignore() {
     fi
 }
 
+# --- setup_templates() ---
+# Detects existing PR/commit templates; generates CortexHawk defaults if missing
+# Args: $1=project_root
+setup_templates() {
+    local project_root="$1"
+
+    [ "$GLOBAL" = true ] && return
+
+    # PR template
+    local pr_template=""
+    for path in ".github/PULL_REQUEST_TEMPLATE.md" ".github/pull_request_template.md" "docs/pull_request_template.md"; do
+        if [ -f "$project_root/$path" ]; then
+            pr_template="$path"
+            break
+        fi
+    done
+    # Also check template directory
+    if [ -z "$pr_template" ] && [ -d "$project_root/.github/PULL_REQUEST_TEMPLATE" ]; then
+        pr_template=".github/PULL_REQUEST_TEMPLATE/"
+    fi
+
+    if [ -n "$pr_template" ]; then
+        green "  PR template found: $pr_template"
+    else
+        mkdir -p "$project_root/.github"
+        cp "$SCRIPT_DIR/templates/github/PULL_REQUEST_TEMPLATE.md" "$project_root/.github/PULL_REQUEST_TEMPLATE.md"
+        green "  PR template created: .github/PULL_REQUEST_TEMPLATE.md"
+    fi
+
+    # Commit template
+    local commit_template=""
+    for path in ".gitmessage" ".github/gitmessage" ".github/commit-template"; do
+        if [ -f "$project_root/$path" ]; then
+            commit_template="$path"
+            break
+        fi
+    done
+
+    if [ -n "$commit_template" ]; then
+        green "  Commit template found: $commit_template"
+    else
+        cp "$SCRIPT_DIR/templates/github/gitmessage" "$project_root/.gitmessage"
+        green "  Commit template created: .gitmessage"
+    fi
+}
+
 # --- run_audit() ---
 run_audit() {
     local project_root="$1"
@@ -641,11 +739,12 @@ generate_hooks_config() {
     fi
 
     if ! command -v python3 >/dev/null 2>&1; then
+        yellow "  Warning: python3 not found — hooks config will use static fallback" >&2
         return 1
     fi
 
-    python3 << PYEOF
-import re, json, sys
+    python3 - "$compose_file" "$hooks_dir" << 'PYEOF'
+import re, json, sys, shlex
 
 def parse_compose(path, hooks_dir):
     """Parse compose.yml and generate Claude Code hooks JSON."""
@@ -679,10 +778,13 @@ def parse_compose(path, hooks_dir):
         # Hook item
         elif line.strip().startswith('- '):
             hook_name = line.strip()[2:].strip()
+            if not re.match(r'^[a-zA-Z0-9_-]+$', hook_name):
+                print(f"Warning: skipping invalid hook name: {hook_name}", file=sys.stderr)
+                continue
             hook_path = f"{hooks_dir}/{hook_name}.sh"
 
             # Build command — hooks read stdin JSON (Claude Code protocol)
-            cmd = f'bash {hook_path}'
+            cmd = f'bash {shlex.quote(hook_path)}'
 
             hook_entry = {"type": "command", "command": cmd}
 
@@ -708,7 +810,7 @@ def parse_compose(path, hooks_dir):
     return result
 
 try:
-    result = parse_compose("$compose_file", "$hooks_dir")
+    result = parse_compose(sys.argv[1], sys.argv[2])
     print(json.dumps(result, indent=2))
 except Exception as e:
     print(f"Error: {e}", file=sys.stderr)
@@ -1176,30 +1278,40 @@ do_update() {
         # Make hooks executable
         chmod +x "$TARGET/hooks/"*.sh 2>/dev/null || true
 
-        # 7b. Regenerate settings.json hooks section from compose.yml
+        # 7b. Regenerate settings.json hooks + merge new permissions from compose.yml
         if [ -f "$SCRIPT_DIR/hooks/compose.yml" ]; then
             local hooks_json
             hooks_json=$(generate_hooks_config "$SCRIPT_DIR/hooks/compose.yml" ".claude/hooks")
-            if [ -n "$hooks_json" ]; then
-                python3 << PYEOF
+            if [ -n "$hooks_json" ] && [ "$hooks_json" != "{}" ]; then
+                echo "$hooks_json" | python3 -c "
 import json, sys
-
-# Read current settings.json to preserve permissions
+hooks = json.load(sys.stdin)
 current = {}
 try:
-    with open('$TARGET/settings.json') as f:
+    with open(sys.argv[1]) as f:
         current = json.load(f)
 except:
     pass
-
-# Merge: keep existing permissions, replace hooks
-hooks = json.loads('''$hooks_json''')
 current['hooks'] = hooks
-
-with open('$TARGET/settings.json', 'w') as f:
+# Merge new permissions from source
+try:
+    with open(sys.argv[2]) as f:
+        src_perms = json.load(f).get('permissions', {})
+    cur_perms = current.get('permissions', {})
+    for key in ('allow', 'deny'):
+        src_list = src_perms.get(key, [])
+        cur_list = cur_perms.get(key, [])
+        added = [p for p in src_list if p not in cur_list]
+        if added:
+            cur_list.extend(added)
+        cur_perms[key] = cur_list
+    current['permissions'] = cur_perms
+except:
+    pass
+with open(sys.argv[1], 'w') as f:
     json.dump(current, f, indent=2)
     f.write('\n')
-PYEOF
+" "$TARGET/settings.json" "$SCRIPT_DIR/settings.json"
                 echo "  Regenerated settings.json hooks from compose.yml"
             fi
         fi
@@ -1214,6 +1326,7 @@ PYEOF
         local target_dir_name=".${TARGET_CLI:-claude}"
         update_gitignore "$(dirname "$TARGET")" "$target_dir_name"
         [ "$TARGET_CLI" = "codex" ] && update_gitignore "$(dirname "$TARGET")" ".agents"
+        setup_templates "$(dirname "$TARGET")"
 
         if [ ! -f "$TARGET/git-workflow.conf" ]; then
             GIT_BRANCHING="direct-main"
@@ -1313,12 +1426,10 @@ do_snapshot() {
         git_push=$(grep '^AUTO_PUSH=' "$TARGET/git-workflow.conf" | cut -d= -f2)
     fi
 
-    # Read custom profile if applicable
+    # Read custom profile if applicable (use PROFILE_FILE from current run, never glob /tmp/)
     local profile_def="null"
-    local custom_profile
-    custom_profile=$(ls /tmp/cortexhawk-custom-*.json 2>/dev/null | head -1)
-    if [ -n "$custom_profile" ] && [ -f "$custom_profile" ]; then
-        profile_def=$(cat "$custom_profile")
+    if [ -n "$PROFILE_FILE" ] && [ -f "$PROFILE_FILE" ]; then
+        profile_def=$(cat "$PROFILE_FILE")
     fi
 
     # Build files checksums from manifest
@@ -1369,7 +1480,7 @@ do_snapshot() {
     [ -n "$git_workflow_content" ] && printf '    "git-workflow.conf": "%s",\n' "$git_workflow_content" >> "$snap_file"
     [ -n "$claude_md_content" ] && printf '    "CLAUDE.md": "%s",\n' "$claude_md_content" >> "$snap_file"
     # Remove trailing comma from last entry
-    sed -i '$ s/,$//' "$snap_file"
+    sed_inplace '$ s/,$//' "$snap_file"
     printf '  }\n' >> "$snap_file"
     printf '}\n' >> "$snap_file"
 
@@ -1875,15 +1986,15 @@ do_restore() {
     if command -v python3 >/dev/null 2>&1; then
         python3 -c "
 import json, sys
-with open('$snap_file') as f:
+with open(sys.argv[1]) as f:
     snap = json.load(f)
 settings = snap.get('settings')
 if settings is not None:
-    with open('$TARGET/settings.json', 'w') as f:
+    with open(sys.argv[2], 'w') as f:
         json.dump(settings, f, indent=2)
         f.write('\n')
     print('  Restored settings.json')
-"
+" "$snap_file" "$TARGET/settings.json"
     else
         echo "  Warning: python3 not found — settings.json not restored from snapshot"
     fi
@@ -1909,23 +2020,24 @@ if settings is not None:
     if grep -q '"file_contents"' "$snap_file" && command -v python3 >/dev/null 2>&1; then
         python3 -c "
 import json, base64, sys, os
-with open('$snap_file') as f:
+snap_file, target_dir = sys.argv[1], sys.argv[2]
+with open(snap_file) as f:
     snap = json.load(f)
 contents = snap.get('file_contents', {})
 for filename, b64data in contents.items():
     try:
         data = base64.b64decode(b64data).decode('utf-8')
         if filename == 'CLAUDE.md':
-            target_path = os.path.dirname('$TARGET') + '/CLAUDE.md'
+            target_path = os.path.dirname(target_dir) + '/CLAUDE.md'
         else:
-            target_path = '$TARGET/' + filename
+            target_path = target_dir + '/' + filename
         os.makedirs(os.path.dirname(target_path), exist_ok=True)
         with open(target_path, 'w') as f:
             f.write(data)
         print(f'  Restored {filename} (from file_contents)')
     except Exception as e:
         print(f'  Warning: could not restore {filename}: {e}', file=sys.stderr)
-"
+" "$snap_file" "$TARGET"
     fi
 
     # Write new manifest
@@ -2312,14 +2424,14 @@ do_list_hooks() {
     printf "  %-20s %-14s %-8s %s\n" "Name" "Event" "Status" "Description"
     printf "  %-20s %-14s %-8s %s\n" "----" "-----" "------" "-----------"
     # Parse hooks.json with python3 for reliable JSON handling
-    python3 << PYEOF
-import json
-with open("$hooks_json") as f:
+    python3 - "$hooks_json" "$compose_file" << 'PYEOF'
+import json, sys
+with open(sys.argv[1]) as f:
     data = json.load(f)
 # Read compose.yml to detect disabled hooks (commented out)
 disabled = set()
 try:
-    with open("$compose_file") as f:
+    with open(sys.argv[2]) as f:
         for line in f:
             stripped = line.strip()
             if stripped.startswith("# - "):
@@ -2368,14 +2480,14 @@ do_toggle_hook() {
             echo "Hook '$hook_name' is already disabled"
             return 0
         fi
-        sed -i "s/^      - ${hook_name}$/      # - ${hook_name}/" "$compose_file"
+        sed_inplace "s/^      - ${hook_name}$/      # - ${hook_name}/" "$compose_file"
         echo "Disabled hook: $hook_name"
     else
         if grep -q "^      - ${hook_name}$" "$compose_file"; then
             echo "Hook '$hook_name' is already enabled"
             return 0
         fi
-        sed -i "s/^      # - ${hook_name}$/      - ${hook_name}/" "$compose_file"
+        sed_inplace "s/^      # - ${hook_name}$/      - ${hook_name}/" "$compose_file"
         echo "Enabled hook: $hook_name"
     fi
     # Regenerate settings.json if target exists
@@ -2383,17 +2495,18 @@ do_toggle_hook() {
     if [ -d "$target" ] && [ -f "$target/settings.json" ]; then
         local hooks_json
         hooks_json=$(generate_hooks_config "$compose_file" ".claude/hooks")
-        if [ -n "$hooks_json" ]; then
-            python3 << PYEOF
-import json
-with open('$target/settings.json') as f:
+        if [ -n "$hooks_json" ] && [ "$hooks_json" != "{}" ]; then
+            echo "$hooks_json" | python3 -c "
+import json, sys
+hooks = json.load(sys.stdin)
+with open(sys.argv[1]) as f:
     settings = json.load(f)
-settings['hooks'] = json.loads('''$hooks_json''')
-with open('$target/settings.json', 'w') as f:
+settings['hooks'] = hooks
+with open(sys.argv[1], 'w') as f:
     json.dump(settings, f, indent=2)
     f.write('\n')
 print('  Regenerated settings.json')
-PYEOF
+" "$target/settings.json"
         fi
     fi
 }
@@ -2441,17 +2554,18 @@ _search_skillsmp() {
     fi
 
     # Parse JSON response with python3
-    python3 << PYEOF
+    python3 - "$tmp_response" "$keyword" << 'PYEOF'
 import json, sys
 try:
-    with open("$tmp_response") as f:
+    response_file, keyword = sys.argv[1], sys.argv[2]
+    with open(response_file) as f:
         data = json.load(f)
     container = data.get("data", {})
     skills = container.get("skills", [])
     pagination = container.get("pagination", {})
     total = pagination.get("total", len(skills))
     if not skills:
-        print("  No skills found matching '$keyword'")
+        print(f"  No skills found matching '{keyword}'")
         print("")
         print("  Try broader terms or check https://skillsmp.com")
         sys.exit(0)
@@ -2474,7 +2588,7 @@ try:
             if len(parts) >= 2:
                 print(f"  Install: ./install.sh --add-skill {parts[0]}/{parts[1]}")
                 break
-    print(f"  Browse all: https://skillsmp.com/?q=$keyword")
+    print(f"  Browse all: https://skillsmp.com/?q={keyword}")
 except Exception as e:
     print(f"  Error parsing response: {e}")
     print("  Falling back to local registry")
@@ -2841,26 +2955,78 @@ install_claude() {
     cp -r "$SCRIPT_DIR/modes/"* "$TARGET/modes/" 2>/dev/null || true
     cp -r "$SCRIPT_DIR/mcp/"* "$TARGET/mcp/" 2>/dev/null || true
 
+    local hooks_json
+    hooks_json=$(generate_hooks_config "$SCRIPT_DIR/hooks/compose.yml" ".claude/hooks")
     if [ ! -f "$TARGET/settings.json" ]; then
-        # Generate settings.json with hooks from compose.yml
-        local hooks_json
-        hooks_json=$(generate_hooks_config "$SCRIPT_DIR/hooks/compose.yml" ".claude/hooks")
+        # Fresh install: generate settings.json from scratch
         if [ -n "$hooks_json" ] && [ "$hooks_json" != "{}" ]; then
-            # Build settings.json with generated hooks
-            python3 -c "
-import json
-permissions = $(cat "$SCRIPT_DIR/settings.json" | python3 -c "import sys,json; d=json.load(sys.stdin); print(json.dumps(d.get('permissions',{})))")
-hooks = $hooks_json
-with open('$TARGET/settings.json', 'w') as f:
+            echo "$hooks_json" | python3 -c "
+import json, sys
+hooks = json.load(sys.stdin)
+with open(sys.argv[1]) as f:
+    permissions = json.load(f).get('permissions', {})
+with open(sys.argv[2], 'w') as f:
     json.dump({'permissions': permissions, 'hooks': hooks}, f, indent=2)
     f.write('\n')
-"
+" "$SCRIPT_DIR/settings.json" "$TARGET/settings.json"
             echo "  Generated settings.json from hooks/compose.yml"
         else
             cp "$SCRIPT_DIR/settings.json" "$TARGET/settings.json"
         fi
     else
-        echo "settings.json already exists — skipping (check manually for updates)"
+        # Merge: preserve user customizations, add new hooks + permissions
+        python3 -c "
+import json, sys, shutil, os
+
+raw = sys.stdin.read().strip()
+hooks = json.loads(raw) if raw else {}
+
+# Load current settings (tolerate corrupted JSON)
+try:
+    with open(sys.argv[1]) as f:
+        current = json.load(f)
+except Exception:
+    backup = sys.argv[1] + '.bak'
+    if os.path.isfile(sys.argv[1]):
+        shutil.copy2(sys.argv[1], backup)
+        print(f'  Warning: settings.json corrupted — backed up to {os.path.basename(backup)}', file=sys.stderr)
+    current = {}
+
+try:
+    with open(sys.argv[2]) as f:
+        source = json.load(f)
+except Exception:
+    source = {}
+
+changes = []
+
+# Merge hooks (regenerate from compose.yml)
+if hooks and hooks != {}:
+    current['hooks'] = hooks
+    changes.append('hooks regenerated')
+
+# Merge permissions (union: keep user additions + add new from source)
+src_perms = source.get('permissions', {})
+cur_perms = current.get('permissions', {})
+for key in ('allow', 'deny'):
+    src_list = src_perms.get(key, [])
+    cur_list = cur_perms.get(key, [])
+    added = [p for p in src_list if p not in cur_list]
+    if added:
+        cur_list.extend(added)
+        changes.append(f'{len(added)} new {key} permission(s)')
+    cur_perms[key] = cur_list
+current['permissions'] = cur_perms
+
+with open(sys.argv[1], 'w') as f:
+    json.dump(current, f, indent=2)
+    f.write('\n')
+
+if changes:
+    print('  Merged settings.json: ' + ', '.join(changes))
+else:
+    print('  settings.json up to date — no merge needed')
+" "$TARGET/settings.json" "$SCRIPT_DIR/settings.json" <<< "${hooks_json:-}"
     fi
 
     PROJECT_ROOT="$(dirname "$TARGET")"
@@ -2897,11 +3063,12 @@ with open('$TARGET/settings.json', 'w') as f:
 
     run_audit "$(dirname "$TARGET")"
     update_gitignore "$(dirname "$TARGET")" ".claude"
+    setup_templates "$(dirname "$TARGET")"
 
     echo ""
     echo "CortexHawk installed successfully for Claude Code!"
     echo ""
-    echo "  32 commands | 20 agents | 36 skills | 9 hooks | 7 modes"
+    echo "  33 commands | 20 agents | 36 skills | 9 hooks | 7 modes"
     echo ""
     do_quickstart
     echo ""
@@ -3749,7 +3916,6 @@ else
             install_codex
             ;;
         auto)
-            local detected
             detected=$(detect_installed_clis)
             if [ -z "$detected" ]; then
                 echo "Error: no supported CLI found (claude, kimi, codex)"
@@ -3758,7 +3924,7 @@ else
             fi
             echo "Auto-detected CLIs: $detected"
             echo ""
-            local auto_count=0
+            auto_count=0
             for cli in $detected; do
                 [ $auto_count -gt 0 ] && echo "" && echo "---" && echo ""
                 case "$cli" in

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cortexhawk",
-  "version": "3.1.0",
+  "version": "3.2.0",
   "description": "Open-source development toolkit for Claude Code — optimized agents, skills, commands, hooks, and modes",
   "bin": {
     "cortexhawk": "./cortexhawk"

package/scripts/autodetect-profile.sh

@@ -57,7 +57,11 @@ $SKILL_JSON
   ]
 }
 EOF
-SKILL_COUNT=$(echo "$SKILLS" | tr ',' '\n' | wc -l | tr -d ' ')
+if [ -z "$SKILLS" ]; then
+    SKILL_COUNT=0
+else
+    SKILL_COUNT=$(echo "$SKILLS" | tr ',' '\n' | wc -l | tr -d ' ')
+fi
 
 # --- Stack snapshot ---
 if [ -d "docs/.context" ]; then

package/scripts/interactive-init.sh

@@ -20,11 +20,13 @@ echo "  1) Claude Code (default) — fully supported"
 echo "  2) Kimi CLI (experimental)"
 echo "  3) Codex CLI (experimental)"
 echo "  4) All (install for all CLIs simultaneously)"
-read -r -p "Choice [1-4] (default: 1): " target_choice
+echo "  5) Auto-detect (install for all CLIs found on system)"
+read -r -p "Choice [1-5] (default: 1): " target_choice
 case "$target_choice" in
     2) TARGET_CLI="kimi" ;;
     3) TARGET_CLI="codex" ;;
     4) TARGET_CLI="all" ;;
+    5) TARGET_CLI="auto" ;;
     *) TARGET_CLI="claude" ;;
 esac
 green "  → $TARGET_CLI"
@@ -32,14 +34,19 @@ echo ""
 
 # --- Step 2: Scope ---
 bold "2. Install Scope"
-echo "  1) Local project — install in current directory (default)"
-echo "  2) Global — install in ~/.${TARGET_CLI}/ (shared across all projects)"
-read -r -p "Choice [1-2] (default: 1): " scope_choice
-case "$scope_choice" in
-    2) GLOBAL=true ;;
-    *) GLOBAL=false ;;
-esac
-green "  → $([ "$GLOBAL" = true ] && echo "global" || echo "local")"
+if [ "$TARGET_CLI" = "all" ] || [ "$TARGET_CLI" = "auto" ]; then
+    GLOBAL=false
+    green "  → local (always local for multi-target install)"
+else
+    echo "  1) Local project — install in current directory (default)"
+    echo "  2) Global — install in ~/.${TARGET_CLI}/ (shared across all projects)"
+    read -r -p "Choice [1-2] (default: 1): " scope_choice
+    case "$scope_choice" in
+        2) GLOBAL=true ;;
+        *) GLOBAL=false ;;
+    esac
+    green "  → $([ "$GLOBAL" = true ] && echo "global" || echo "local")"
+fi
 echo ""
 
 # --- Step 3: Skills ---
@@ -122,7 +129,7 @@ echo ""
 read -r -p "  API key (press Enter to skip): " SKILLSMP_KEY
 if [ -n "$SKILLSMP_KEY" ]; then
     if [ -f ".env" ] && grep -q '^SKILLSMP_API_KEY=' .env 2>/dev/null; then
-        sed -i "s/^SKILLSMP_API_KEY=.*/SKILLSMP_API_KEY=$SKILLSMP_KEY/" .env
+        sed_inplace "s/^SKILLSMP_API_KEY=.*/SKILLSMP_API_KEY=$SKILLSMP_KEY/" .env
     else
         echo "SKILLSMP_API_KEY=$SKILLSMP_KEY" >> .env
     fi

package/scripts/refresh-context.sh

@@ -0,0 +1,51 @@
+#!/bin/bash
+# refresh-context.sh — Regenerate docs/.context/_shared.md mid-session
+# Called by agents after modifying backlog, completing tasks, or committing code
+
+[ -d "docs/.context" ] && [ ! -L "docs/.context" ] || exit 0
+
+SHARED="docs/.context/_shared.md"
+
+echo "# Shared Context" > "$SHARED"
+echo "" >> "$SHARED"
+echo "_Auto-generated at $(date '+%Y-%m-%d %H:%M'). Last refresh: $(date '+%H:%M:%S')._" >> "$SHARED"
+echo "" >> "$SHARED"
+
+# Backlog summary
+if [ -f "docs/backlog.md" ]; then
+    ACTIVE=$(grep -c '| todo |' docs/backlog.md 2>/dev/null || true)
+    : "${ACTIVE:=0}"
+    DEFERRED=$(grep -c '| deferred |' docs/backlog.md 2>/dev/null || true)
+    : "${DEFERRED:=0}"
+    DONE=$(grep -c '| done |' docs/backlog.md 2>/dev/null || true)
+    : "${DONE:=0}"
+    echo "## Backlog" >> "$SHARED"
+    echo "- Active: $ACTIVE | Deferred: $DEFERRED | Done: $DONE" >> "$SHARED"
+    grep '| todo |' docs/backlog.md >> "$SHARED" 2>/dev/null || true
+    echo "" >> "$SHARED"
+fi
+
+# Recent commits
+if git rev-parse --is-inside-work-tree > /dev/null 2>&1; then
+    echo "## Recent Commits" >> "$SHARED"
+    git log --oneline -5 2>/dev/null >> "$SHARED" || true
+    echo "" >> "$SHARED"
+fi
+
+# User context
+if [ -f "docs/.context/_user.md" ]; then
+    cat "docs/.context/_user.md" >> "$SHARED"
+    echo "" >> "$SHARED"
+fi
+
+# Active warnings
+echo "## Warnings" >> "$SHARED"
+WARNINGS=0
+if [ -f ".env.example" ] && [ ! -f ".env" ]; then
+    echo "- .env missing — copy from .env.example" >> "$SHARED"
+    WARNINGS=$((WARNINGS + 1))
+fi
+if [ "$WARNINGS" -eq 0 ]; then
+    echo "- None" >> "$SHARED"
+fi
+echo "" >> "$SHARED"