@karajan-family/code 4.21.0

package/scripts/install-binary.ps1

@@ -0,0 +1,174 @@
+<#
+.SYNOPSIS
+  Karajan Code installer for Windows — guarantees a COMPLETE install (KJC-TSK-0667).
+
+.DESCRIPTION
+  Run it with:
+    irm https://karajancode.com/install.ps1 | iex
+
+  Default route: npm — the full product (CLI + RAG + HU Board + MCP).
+    1. Node >= 22.12 present  -> npm install -g karajan-code
+    2. No usable Node         -> auto-provision the official Node LTS zip into
+       ~\.karajan\node (checksum-verified, nothing system-wide touched),
+       install karajan-code with it, drop kj/karajan-mcp wrappers into the
+       install dir and add it to the user PATH.
+  Standalone route (CLI only, no native-module features — RAG/board/MCP
+  unavailable): opt-in with $env:KJ_STANDALONE = "1".
+
+  Env overrides (irm|iex cannot take parameters): KJ_VERSION, KJ_INSTALL_DIR,
+  KJ_STANDALONE. Windows PowerShell 5.1 compatible.
+#>
+$ErrorActionPreference = "Stop"
+
+$repo = "manufosela/karajan-code"
+$version = if ($env:KJ_VERSION) { $env:KJ_VERSION } else { "latest" }
+$installDir = if ($env:KJ_INSTALL_DIR) { $env:KJ_INSTALL_DIR } else { Join-Path $env:LOCALAPPDATA "Karajan" }
+$mode = if ($env:KJ_STANDALONE -eq "1") { "standalone" } else { "full" }
+$nodeMajor = 22
+$nodeMinMinor = 12
+
+function Get-NpmPkg {
+  if ($version -eq "latest") { "karajan-code" } else { "karajan-code@" + $version.TrimStart("v") }
+}
+
+function Test-NodeOk {
+  $node = Get-Command node -ErrorAction SilentlyContinue
+  if (-not $node) { return $false }
+  $v = (& node --version) 2>$null
+  if (-not $v) { return $false }
+  $parts = $v.TrimStart("v").Split(".")
+  $major = [int]$parts[0]; $minor = [int]$parts[1]
+  return ($major -gt $nodeMajor) -or ($major -eq $nodeMajor -and $minor -ge $nodeMinMinor)
+}
+
+function Add-UserPath([string]$dir) {
+  $userPath = [Environment]::GetEnvironmentVariable("Path", "User")
+  $parts = @()
+  if ($userPath) { $parts = $userPath.Split(";") | Where-Object { $_ -ne "" } }
+  $already = $parts | Where-Object { $_.TrimEnd("\") -ieq $dir.TrimEnd("\") }
+  if (-not $already) {
+    $newPath = if ($userPath) { "$userPath;$dir" } else { $dir }
+    [Environment]::SetEnvironmentVariable("Path", $newPath, "User")
+    Write-Host "kj-install: added '$dir' to your user PATH. Open a NEW terminal to use 'kj'."
+  }
+}
+
+$tmp = Join-Path ([System.IO.Path]::GetTempPath()) ("kj-install-" + [System.Guid]::NewGuid().ToString("N"))
+New-Item -ItemType Directory -Path $tmp -Force | Out-Null
+
+try {
+  if ($mode -eq "full") {
+    if (Test-NodeOk) {
+      Write-Host "kj-install: Node $(& node --version) found — installing via npm (full product)..."
+      & npm install -g (Get-NpmPkg)
+      if ($LASTEXITCODE -ne 0) { throw "npm install failed (exit $LASTEXITCODE)." }
+      Write-Host "kj-install: installed. Run 'kj doctor' next, then 'kj install-tools' to complete the whole stack."
+      return
+    }
+
+    Write-Host "kj-install: no usable Node (need >= $nodeMajor.$nodeMinMinor) — provisioning official Node LTS into ~\.karajan\node (nothing system-wide)..."
+    $dist = "https://nodejs.org/dist/latest-v$nodeMajor.x"
+    $shaFile = Join-Path $tmp "SHASUMS256.txt"
+    Invoke-WebRequest -Uri "$dist/SHASUMS256.txt" -OutFile $shaFile -UseBasicParsing
+    $shaLines = Get-Content $shaFile
+    $assetLine = $shaLines | Where-Object { $_ -match "node-v[0-9.]+-win-x64\.zip" } | Select-Object -First 1
+    if (-not $assetLine) { throw "no official Node build for win-x64 in $dist" }
+    $nodeAsset = ($assetLine -split "\s+")[1]
+    $expected = ($assetLine -split "\s+")[0].ToLower()
+
+    Write-Host "kj-install: downloading $nodeAsset..."
+    $zip = Join-Path $tmp $nodeAsset
+    Invoke-WebRequest -Uri "$dist/$nodeAsset" -OutFile $zip -UseBasicParsing
+    $actual = (Get-FileHash -Algorithm SHA256 -Path $zip).Hash.ToLower()
+    if ($expected -ne $actual) { throw "Node checksum mismatch — aborting, nothing installed." }
+
+    # Stage everything (extract + npm install) and only swap into place once
+    # EVERYTHING succeeded — a failure must never destroy a previous working
+    # ~\.karajan\node.
+    $nodeHome = Join-Path $env:USERPROFILE ".karajan\node"
+    $staging = "$nodeHome.staging.$PID"
+    $extract = Join-Path $tmp "extract"
+    if (Test-Path $staging) { Remove-Item -Recurse -Force $staging }
+    Expand-Archive -Path $zip -DestinationPath $extract -Force
+    # The zip wraps everything in a node-vX.Y.Z-win-x64\ top folder — unwrap it.
+    $inner = Get-ChildItem -Directory $extract | Select-Object -First 1
+    New-Item -ItemType Directory -Path (Split-Path $staging) -Force | Out-Null
+    Move-Item -Path $inner.FullName -Destination $staging
+
+    Write-Host "kj-install: installing karajan-code with the provisioned Node..."
+    $env:Path = "$staging;$env:Path"
+    # Explicit --prefix: the official Windows npm ships a builtin prefix of
+    # %AppData%\npm — without this the global shims would land OUTSIDE the
+    # self-contained ~\.karajan\node home (on Windows, prefix root IS the
+    # global bin dir, so shims land at $staging\kj.cmd).
+    & (Join-Path $staging "npm.cmd") install -g --prefix "$staging" (Get-NpmPkg)
+    if ($LASTEXITCODE -ne 0) { throw "npm install failed with the provisioned Node (exit $LASTEXITCODE)." }
+    foreach ($bin in @("kj", "karajan-mcp")) {
+      if (-not (Test-Path (Join-Path $staging "$bin.cmd"))) {
+        throw "npm reported success but the $bin shim is missing from the staged prefix — the full product needs both kj and karajan-mcp. Aborting, nothing swapped."
+      }
+    }
+
+    # Swap keeping the previous install recoverable: park it as a backup,
+    # move the staged one in, restore the backup if that move fails.
+    $backup = "$nodeHome.old.$PID"
+    if (Test-Path $nodeHome) { Move-Item -Path $nodeHome -Destination $backup -Force }
+    try {
+      Move-Item -Path $staging -Destination $nodeHome
+    } catch {
+      if (Test-Path $backup) { Move-Item -Path $backup -Destination $nodeHome -Force }
+      throw "could not move the staged install into place (previous install restored). $_"
+    }
+    if (Test-Path $backup) { Remove-Item -Recurse -Force $backup }
+
+    # Wrappers, not copies: npm's own .cmd shims live inside nodeHome and
+    # resolve node via their folder; these put nodeHome on PATH for children
+    # (kj spawns node tooling) and forward every argument.
+    New-Item -ItemType Directory -Path $installDir -Force | Out-Null
+    foreach ($bin in @("kj", "karajan-mcp")) {
+      $shim = Join-Path $nodeHome "$bin.cmd"
+      $wrapper = @(
+        "@echo off",
+        "set `"PATH=$nodeHome;%PATH%`"",
+        "`"$shim`" %*"
+      )
+      Set-Content -Path (Join-Path $installDir "$bin.cmd") -Value $wrapper -Encoding ASCII
+    }
+    Add-UserPath $installDir
+    $installed = (& (Join-Path $installDir "kj.cmd") --version) 2>$null
+    Write-Host "kj-install: installed kj $installed (full product) — kj at $(Join-Path $installDir 'kj.cmd')"
+    Write-Host "kj-install: next — run 'kj doctor', then 'kj install-tools' to complete the whole stack."
+    return
+  }
+
+  # --- Standalone route: prebuilt single binary (CLI only). ---
+  Write-Host "kj-install: standalone mode — single binary, NO native-module features (RAG, HU Board and MCP need the npm install)."
+  $asset = "kj-win-x64.exe"
+  $base = if ($version -eq "latest") { "https://github.com/$repo/releases/latest/download" }
+          else { "https://github.com/$repo/releases/download/$version" }
+
+  $binTmp = Join-Path $tmp "kj.exe"
+  $shaTmp = Join-Path $tmp "kj.exe.sha256"
+  Write-Host "kj-install: downloading $asset ($version)..."
+  Invoke-WebRequest -Uri "$base/$asset" -OutFile $binTmp -UseBasicParsing
+  Invoke-WebRequest -Uri "$base/$asset.sha256" -OutFile $shaTmp -UseBasicParsing
+
+  $shaLine = (Get-Content $shaTmp | Where-Object { $_ -notmatch "SHA256|CertUtil" } | Select-Object -First 1)
+  $expected = ($shaLine -replace "[^0-9A-Fa-f]", "").ToLower()
+  $actual = (Get-FileHash -Algorithm SHA256 -Path $binTmp).Hash.ToLower()
+  if ($expected.Length -ne 64 -or $expected -ne $actual) {
+    throw "checksum mismatch (expected '$expected', got '$actual'). Aborting, nothing installed."
+  }
+
+  New-Item -ItemType Directory -Path $installDir -Force | Out-Null
+  $dest = Join-Path $installDir "kj.exe"
+  Move-Item -Path $binTmp -Destination $dest -Force
+  # Clear the mark-of-the-web on the copy we just checksum-verified ourselves.
+  Unblock-File -Path $dest -ErrorAction SilentlyContinue
+  Add-UserPath $installDir
+  $installed = (& $dest --version) 2>$null
+  Write-Host "kj-install: installed standalone kj $installed to $dest"
+  Write-Host "kj-install: next — run 'kj doctor'. For the full product later: re-run without KJ_STANDALONE."
+} finally {
+  Remove-Item -Path $tmp -Recurse -Force -ErrorAction SilentlyContinue
+}

package/scripts/install-binary.sh

@@ -0,0 +1,159 @@
+#!/bin/sh
+# Karajan Code installer — guarantees a COMPLETE install (KJC-TSK-0658).
+#
+#   curl -fsSL https://karajancode.com/install.sh | sh
+#
+# Default route: npm — the full product (CLI + RAG + HU Board + MCP).
+#   1. Node >= 22.12 present  → npm install -g karajan-code
+#   2. No usable Node         → auto-provision official Node LTS into
+#      ~/.karajan/node (checksum-verified, nothing system-wide touched),
+#      install karajan-code with it, symlink kj into ~/.local/bin.
+# Standalone route (CLI only, no native-module features — RAG/board/MCP
+# unavailable): opt-in with `--standalone` or KJ_STANDALONE=1.
+#
+# POSIX sh only. Env overrides: KJ_VERSION, KJ_INSTALL_DIR.
+set -eu
+
+REPO="manufosela/karajan-code"
+VERSION="${KJ_VERSION:-latest}"
+INSTALL_DIR="${KJ_INSTALL_DIR:-$HOME/.local/bin}"
+NODE_MAJOR="22"
+NODE_MIN_MINOR="12"
+MODE="full"
+[ "${1:-}" = "--standalone" ] && MODE="standalone"
+[ "${KJ_STANDALONE:-0}" = "1" ] && MODE="standalone"
+
+die() { echo "kj-install: $1" >&2; exit 1; }
+
+# --- Detect OS/arch (shared by both routes). ---
+os="$(uname -s)"; arch="$(uname -m)"
+case "$os" in
+  Linux) os="linux" ;;
+  Darwin) os="darwin" ;;
+  *) die "unsupported OS '$os'. Supported: Linux, macOS." ;;
+esac
+case "$arch" in
+  x86_64 | amd64) arch="x64" ;;
+  arm64 | aarch64) arch="arm64" ;;
+  *) die "unsupported architecture '$arch'" ;;
+esac
+
+# --- Downloader + checksum tool. ---
+if command -v curl >/dev/null 2>&1; then fetch() { curl -fsSL "$1" -o "$2"; }
+elif command -v wget >/dev/null 2>&1; then fetch() { wget -qO "$2" "$1"; }
+else die "need curl or wget"; fi
+if command -v sha256sum >/dev/null 2>&1; then sha256() { sha256sum "$1" | cut -d' ' -f1; }
+elif command -v shasum >/dev/null 2>&1; then sha256() { shasum -a 256 "$1" | cut -d' ' -f1; }
+else die "need sha256sum or shasum to verify downloads"; fi
+
+tmp="$(mktemp -d "${TMPDIR:-/tmp}/kj-install.XXXXXX")"
+trap 'rm -rf "$tmp"' EXIT INT TERM
+
+path_hint() {
+  case ":${PATH}:" in
+    *":$1:"*) ;;
+    *) echo "kj-install: add '$1' to your PATH:  export PATH=\"$1:\$PATH\"  (persist it in ~/.bashrc / ~/.zshrc)" ;;
+  esac
+}
+
+# --- Is there a usable Node (>= NODE_MAJOR.NODE_MIN_MINOR)? ---
+node_ok() {
+  command -v node >/dev/null 2>&1 || return 1
+  v="$(node --version 2>/dev/null | sed 's/^v//')"
+  major="${v%%.*}"; rest="${v#*.}"; minor="${rest%%.*}"
+  [ "$major" -gt "$NODE_MAJOR" ] 2>/dev/null && return 0
+  [ "$major" -eq "$NODE_MAJOR" ] 2>/dev/null && [ "$minor" -ge "$NODE_MIN_MINOR" ] 2>/dev/null
+}
+
+npm_pkg() { if [ "$VERSION" = "latest" ]; then echo "karajan-code"; else echo "karajan-code@${VERSION#v}"; fi; }
+
+if [ "$MODE" = "full" ]; then
+  if node_ok; then
+    echo "kj-install: Node $(node --version) found — installing via npm (full product)..."
+    npm install -g "$(npm_pkg)" || die "npm install failed. If it was a permissions error, set a user prefix (npm config set prefix ~/.local) and re-run."
+    echo "kj-install: installed $(kj --version 2>/dev/null || echo karajan-code). Run 'kj doctor' next."
+    exit 0
+  fi
+
+  echo "kj-install: no usable Node (need >= ${NODE_MAJOR}.${NODE_MIN_MINOR}) — provisioning official Node LTS into ~/.karajan/node (nothing system-wide)..."
+  dist="https://nodejs.org/dist/latest-v${NODE_MAJOR}.x"
+  fetch "${dist}/SHASUMS256.txt" "${tmp}/SHASUMS256.txt" || die "could not fetch the Node checksum list"
+  node_asset="$(grep -o "node-v[0-9.]*-${os}-${arch}\.tar\.gz" "${tmp}/SHASUMS256.txt" | head -1)"
+  [ -n "$node_asset" ] || die "no official Node build for ${os}-${arch}"
+  echo "kj-install: downloading ${node_asset}..."
+  fetch "${dist}/${node_asset}" "${tmp}/${node_asset}" || die "could not download Node"
+  expected="$(grep "${node_asset}\$" "${tmp}/SHASUMS256.txt" | head -1 | cut -d' ' -f1)"
+  actual="$(sha256 "${tmp}/${node_asset}")"
+  [ "$expected" = "$actual" ] || die "Node checksum mismatch — aborting, nothing installed"
+
+  # Stage the whole install (extract + npm install) in a sibling dir and only
+  # swap it into place once EVERYTHING succeeded — a failed download/extract/
+  # install must never destroy a previous working ~/.karajan/node.
+  node_home="$HOME/.karajan/node"
+  staging="${node_home}.staging.$$"
+  rm -rf "$staging"; mkdir -p "$staging"
+  trap 'rm -rf "$tmp" "$staging"' EXIT INT TERM
+  tar -xzf "${tmp}/${node_asset}" -C "$staging" --strip-components=1 || die "could not extract Node"
+
+  echo "kj-install: installing karajan-code with the provisioned Node..."
+  PATH="${staging}/bin:$PATH" "${staging}/bin/npm" install -g "$(npm_pkg)" || die "npm install failed with the provisioned Node"
+
+  # Swap keeping the previous install recoverable at EVERY instant: park it
+  # as a backup, arm a trap that restores it on any exit (signal included),
+  # move the staged one in, and only then disarm the trap and drop the
+  # backup — the user can never end up without a working install.
+  backup="${node_home}.old.$$"
+  if [ -e "$node_home" ]; then
+    mv "$node_home" "$backup" || die "could not park the previous install"
+    trap '[ -e "$node_home" ] || mv "$backup" "$node_home" 2>/dev/null; rm -rf "$tmp" "$staging"' EXIT INT TERM
+  fi
+  mv "$staging" "$node_home" || die "could not move the staged install into place (previous install restored)"
+  trap 'rm -rf "$tmp"' EXIT INT TERM
+  rm -rf "$backup"
+  mkdir -p "$INSTALL_DIR"
+  # Wrappers, not symlinks: the shebang (#!/usr/bin/env node) must find the
+  # provisioned Node even though it is not on the user's PATH.
+  for bin in kj karajan-mcp; do
+    [ -e "${node_home}/bin/${bin}" ] || continue
+    {
+      echo '#!/bin/sh'
+      echo "export PATH=\"${node_home}/bin:\$PATH\""
+      echo "exec \"${node_home}/bin/${bin}\" \"\$@\""
+    } >"${INSTALL_DIR}/${bin}"
+    chmod +x "${INSTALL_DIR}/${bin}"
+  done
+  installed="$("${INSTALL_DIR}/kj" --version 2>/dev/null || echo '?')"
+  echo "kj-install: installed kj ${installed} (full product) — kj at ${INSTALL_DIR}/kj"
+  path_hint "$INSTALL_DIR"
+  echo "kj-install: next — run 'kj doctor', then 'kj install-tools' to complete the whole stack."
+  exit 0
+fi
+
+# --- Standalone route: prebuilt single binary (CLI only). ---
+echo "kj-install: standalone mode — single binary, NO native-module features (RAG, HU Board and MCP need the npm install)."
+target="${os}-${arch}"
+case "$target" in
+  linux-x64 | darwin-arm64) ;;
+  *) die "no prebuilt binary for '$target' (available: linux-x64, darwin-arm64) — run without --standalone for the npm route" ;;
+esac
+asset="kj-${target}"
+if [ "$VERSION" = "latest" ]; then base="https://github.com/${REPO}/releases/latest/download"
+else base="https://github.com/${REPO}/releases/download/${VERSION}"; fi
+
+echo "kj-install: downloading ${asset} (${VERSION})..."
+fetch "${base}/${asset}" "${tmp}/kj" || die "could not download ${base}/${asset}"
+fetch "${base}/${asset}.sha256" "${tmp}/kj.sha256" || die "could not download the checksum for ${asset}"
+expected="$(cut -d' ' -f1 <"${tmp}/kj.sha256")"
+actual="$(sha256 "${tmp}/kj")"
+[ "$expected" = "$actual" ] || die "checksum mismatch — aborting, nothing installed"
+
+chmod +x "${tmp}/kj"
+mkdir -p "$INSTALL_DIR"
+mv -f "${tmp}/kj" "${INSTALL_DIR}/kj"
+if [ "$os" = "darwin" ] && command -v xattr >/dev/null 2>&1; then
+  xattr -d com.apple.quarantine "${INSTALL_DIR}/kj" 2>/dev/null || true
+fi
+installed="$("${INSTALL_DIR}/kj" --version 2>/dev/null || echo '?')"
+echo "kj-install: installed standalone kj ${installed} to ${INSTALL_DIR}/kj"
+path_hint "$INSTALL_DIR"
+echo "kj-install: next — run 'kj doctor'. For the full product later: re-run this installer without --standalone."

package/scripts/install-guard-all-repos.sh

@@ -0,0 +1,85 @@
+#!/bin/bash
+#
+# Installs the AI Attribution Guard workflow in all repos of a GitHub user.
+# Requires: gh CLI authenticated with admin/push permissions.
+#
+# Usage:
+#   ./scripts/install-guard-all-repos.sh              # dry-run
+#   ./scripts/install-guard-all-repos.sh --apply       # install in all repos
+#
+# What it does:
+#   - Creates .github/workflows/ai-attribution-guard.yml in each repo
+#   - Skips repos that already have the file
+#   - Skips archived repos
+
+set -euo pipefail
+
+OWNER="${GH_OWNER:-manufosela}"
+APPLY=false
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+WORKFLOW_FILE="$SCRIPT_DIR/ai-attribution-guard.yml"
+
+if [[ "${1:-}" == "--apply" ]]; then
+  APPLY=true
+fi
+
+if [[ ! -f "$WORKFLOW_FILE" ]]; then
+  echo "ERROR: $WORKFLOW_FILE not found"
+  exit 1
+fi
+
+CONTENT=$(base64 -w 0 "$WORKFLOW_FILE")
+
+echo "=== Install AI Attribution Guard in all repos of $OWNER ==="
+echo ""
+
+if [[ "$APPLY" == false ]]; then
+  echo "  DRY RUN mode. Use --apply to actually install."
+  echo ""
+fi
+
+REPOS=$(gh repo list "$OWNER" --limit 500 --json name,isArchived \
+  --jq '.[] | select(.isArchived == false) | .name')
+
+TOTAL=0
+INSTALLED=0
+SKIPPED=0
+FAILED=0
+
+while read -r REPO; do
+  [ -z "$REPO" ] && continue
+  TOTAL=$((TOTAL + 1))
+
+  # Check if workflow already exists
+  EXISTS=$(gh api "repos/$OWNER/$REPO/contents/.github/workflows/ai-attribution-guard.yml" --jq '.sha' 2>/dev/null || echo "")
+
+  if [[ -n "$EXISTS" ]]; then
+    echo "  SKIP  $REPO — workflow already exists"
+    SKIPPED=$((SKIPPED + 1))
+    continue
+  fi
+
+  if [[ "$APPLY" == false ]]; then
+    echo "  WOULD $REPO"
+    continue
+  fi
+
+  if gh api "repos/$OWNER/$REPO/contents/.github/workflows/ai-attribution-guard.yml" -X PUT \
+    -f message="chore: add AI attribution guard workflow" \
+    -f content="$CONTENT" \
+    --jq '.commit.sha' 2>/dev/null; then
+    echo "  OK    $REPO"
+    INSTALLED=$((INSTALLED + 1))
+  else
+    echo "  FAIL  $REPO — check permissions"
+    FAILED=$((FAILED + 1))
+  fi
+
+done <<< "$REPOS"
+
+echo ""
+echo "=== Summary ==="
+echo "  Total:     $TOTAL"
+echo "  Installed: $INSTALLED"
+echo "  Skipped:   $SKIPPED"
+echo "  Failed:    $FAILED"

package/scripts/install-kj.sh

@@ -0,0 +1,193 @@
+#!/bin/sh
+# Karajan Code - Universal Installer
+# Usage: curl -fsSL https://raw.githubusercontent.com/manufosela/karajan-code/main/scripts/install-kj.sh | sh
+#
+# Installs karajan-code globally via npm if Node.js >= 18 is available.
+# If Node.js is not installed, prints platform-specific instructions.
+
+# --- Color support ---
+setup_colors() {
+  if [ -t 1 ] && command -v tput >/dev/null 2>&1 && [ "$(tput colors 2>/dev/null || echo 0)" -ge 8 ]; then
+    BOLD="$(tput bold)"
+    GREEN="$(tput setaf 2)"
+    YELLOW="$(tput setaf 3)"
+    RED="$(tput setaf 1)"
+    CYAN="$(tput setaf 6)"
+    RESET="$(tput sgr0)"
+  else
+    BOLD="" GREEN="" YELLOW="" RED="" CYAN="" RESET=""
+  fi
+}
+
+info()    { printf '%s[info]%s  %s\n' "$CYAN" "$RESET" "$1"; }
+success() { printf '%s[ok]%s    %s\n' "$GREEN" "$RESET" "$1"; }
+warn()    { printf '%s[warn]%s  %s\n' "$YELLOW" "$RESET" "$1"; }
+error()   { printf '%s[error]%s %s\n' "$RED" "$RESET" "$1"; }
+
+# --- Platform detection ---
+detect_platform() {
+  OS="$(uname -s)"
+  ARCH="$(uname -m)"
+
+  case "$OS" in
+    Linux*)  PLATFORM="linux" ;;
+    Darwin*) PLATFORM="macos" ;;
+    MINGW*|MSYS*|CYGWIN*) PLATFORM="windows" ;;
+    *)       PLATFORM="unknown" ;;
+  esac
+
+  case "$ARCH" in
+    x86_64|amd64) ARCH="x64" ;;
+    aarch64|arm64) ARCH="arm64" ;;
+    *)             ARCH="$ARCH" ;;
+  esac
+}
+
+# --- Check Node.js ---
+check_node() {
+  if ! command -v node >/dev/null 2>&1; then
+    return 1
+  fi
+
+  NODE_VERSION="$(node --version 2>/dev/null | sed 's/^v//')"
+  NODE_MAJOR="$(echo "$NODE_VERSION" | cut -d. -f1)"
+
+  if [ "$NODE_MAJOR" -lt 18 ] 2>/dev/null; then
+    warn "Node.js v${NODE_VERSION} found, but v18+ is required."
+    return 1
+  fi
+
+  return 0
+}
+
+# --- Print Node.js install instructions ---
+print_node_instructions() {
+  echo ""
+  error "Node.js >= 18 is required but not found."
+  echo ""
+  printf '%sInstall Node.js for your platform:%s\n' "$BOLD" "$RESET"
+  echo ""
+
+  case "$PLATFORM" in
+    linux)
+      echo "  Option 1 - nvm (recommended):"
+      echo "    curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash"
+      echo "    nvm install 22"
+      echo ""
+      echo "  Option 2 - NodeSource:"
+      echo "    curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -"
+      echo "    sudo apt-get install -y nodejs"
+      ;;
+    macos)
+      echo "  Option 1 - nvm (recommended):"
+      echo "    curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash"
+      echo "    nvm install 22"
+      echo ""
+      echo "  Option 2 - Homebrew:"
+      echo "    brew install node@22"
+      ;;
+    windows)
+      echo "  Option 1 - nvm-windows:"
+      echo "    https://github.com/coreybutler/nvm-windows/releases"
+      echo ""
+      echo "  Option 2 - Download installer:"
+      echo "    https://nodejs.org/en/download/"
+      ;;
+    *)
+      echo "  Download from: https://nodejs.org/en/download/"
+      ;;
+  esac
+
+  echo ""
+  echo "  After installing Node.js, re-run this script:"
+  echo "    curl -fsSL https://raw.githubusercontent.com/manufosela/karajan-code/main/scripts/install-kj.sh | sh"
+  echo ""
+}
+
+# --- Install via npm ---
+install_karajan() {
+  info "Installing karajan-code via npm..."
+  echo ""
+
+  if npm install -g karajan-code; then
+    success "karajan-code installed successfully."
+  else
+    echo ""
+    error "npm install failed."
+    echo ""
+    echo "  Common fixes:"
+    echo "    - Permission error? Use: sudo npm install -g karajan-code"
+    echo "    - Or configure npm prefix: https://docs.npmjs.com/resolving-eacces-permissions-errors-when-installing-packages-globally"
+    echo ""
+    exit 1
+  fi
+}
+
+# --- Verify installation ---
+verify_install() {
+  echo ""
+  if command -v kj >/dev/null 2>&1; then
+    KJ_VERSION="$(kj --version 2>/dev/null || echo "unknown")"
+    success "kj ${KJ_VERSION} is ready."
+  else
+    warn "kj command not found in PATH. You may need to restart your shell."
+    return 1
+  fi
+}
+
+# --- Run kj init ---
+run_init() {
+  if command -v kj >/dev/null 2>&1; then
+    info "Running kj init to detect installed agents..."
+    echo ""
+    kj init --no-interactive 2>/dev/null || true
+    echo ""
+  fi
+}
+
+# --- Print next steps ---
+print_next_steps() {
+  echo ""
+  printf '%s%s--- Karajan Code installed ---%s\n' "$BOLD" "$GREEN" "$RESET"
+  echo ""
+  echo "  Next steps:"
+  echo ""
+  echo "    1. Go to a project directory:"
+  echo "       cd your-project/"
+  echo ""
+  echo "    2. Run from CLI:"
+  echo "       kj run \"Add input validation with tests\""
+  echo ""
+  echo "    3. Or use as MCP server inside Claude Code / Codex:"
+  echo "       The MCP server auto-registers during install."
+  echo "       Open kj-tail in a separate terminal to see pipeline output."
+  echo ""
+  echo "  Docs: https://karajancode.com"
+  echo ""
+}
+
+# --- Main ---
+main() {
+  setup_colors
+
+  echo ""
+  printf '%s%sKarajan Code Installer%s\n' "$BOLD" "$CYAN" "$RESET"
+  echo ""
+
+  detect_platform
+  info "Detected: ${PLATFORM} (${ARCH})"
+
+  if ! check_node; then
+    print_node_instructions
+    exit 1
+  fi
+
+  success "Node.js v${NODE_VERSION} detected."
+
+  install_karajan
+  verify_install
+  run_init
+  print_next_steps
+}
+
+main