agentic-loop 3.22.1 → 3.26.0

package/.claude/skills/prd-check/SKILL.md

@@ -4,7 +4,7 @@ description: Run PRD validation to check story quality, test coverage, and struc
 
 # PRD Check
 
-Run PRD validation on demand to check story quality, test coverage, and structure before starting the autonomous loop.
+Run PRD validation on demand to check story quality, test coverage, and structure before starting the autonomous loop. Cross-references against learned signs and past failure patterns.
 
 ## Instructions
 
@@ -17,32 +17,89 @@ ls -la .ralph/prd.json 2>/dev/null || echo "NOT_FOUND"
 ```
 
 If no PRD exists, tell the user:
-> No PRD found at `.ralph/prd.json`. Generate one first with `/idea` or `/prd`.
+> No PRD found at `.ralph/prd.json`. Generate one first with `/prd`.
 
 **STOP** if no PRD found.
 
-### Step 2: Run Validation (dry-run)
+### Step 2: Load Project Knowledge
 
-Run validation without auto-fix so you can present results and let the user decide:
+Read the project's accumulated knowledge:
+
+1. Read signs:
+   ```bash
+   cat .ralph/signs.json 2>/dev/null
+   ```
+
+2. Read suggested signs (last 50 lines — file can be huge):
+   ```bash
+   tail -50 .ralph/suggested-signs.txt 2>/dev/null
+   ```
+
+3. Read recent progress for failure patterns:
+   ```bash
+   tail -100 .ralph/progress.txt 2>/dev/null
+   ```
+
+### Step 3: Run Structural Validation (dry-run)
 
 ```bash
 npx ralph prd-check --dry-run 2>&1
 ```
 
-### Step 3: Present Results
+Present any structural issues found.
+
+### Step 4: Cross-Reference Against Signs
+
+Read `.ralph/prd.json` and for each story, check if any sign applies:
+
+- **Backend signs** → check against backend stories
+- **Frontend signs** → check against frontend stories
+- **General signs** → check against all stories
+
+For each applicable sign, verify the story's `acceptanceCriteria`, `constraints`,
+`notes`, or `testSteps` reflect the pattern. Flag stories that should account for
+a sign but don't.
+
+**Examples:**
+- Sign: "Always use bcrypt cost 10+ for passwords" → Flag auth stories missing
+  bcrypt in acceptanceCriteria
+- Sign: "Use date-fns instead of moment.js" → Flag frontend stories that create
+  date utilities without this constraint
+- Sign: "Add data-testid for Playwright selectors" → Flag frontend stories missing
+  this in constraints
+
+### Step 5: Check Against Suggested Learnings
+
+Scan `suggested-signs.txt` for patterns relevant to the current PRD's feature area.
+Flag any recurring failure patterns that the PRD's stories don't address.
+
+### Step 6: Present Results
+
+Summarize all findings in categories:
 
-Show the validation output to the user. If there are issues, summarize them clearly.
+> **Structural Issues** (from prd-check):
+> - [list]
+>
+> **Sign Conflicts** (stories that don't account for known patterns):
+> - TASK-003: Missing sign "bcrypt cost 10+" in auth story
+> - TASK-005: Missing sign "data-testid attributes" in frontend story
+>
+> **Suggested Improvements** (from past learnings):
+> - [relevant patterns from suggested-signs.txt]
 
-If issues were found, ask:
-> "Would you like me to fix these issues in the PRD?"
+Ask: "Would you like me to fix these issues in the PRD?"
 
 **STOP and wait for user response.**
 
-If the user says yes, read `.ralph/prd.json`, fix the issues following PRD best practices (executable testSteps with curl/pytest/playwright, apiContract for backends, testUrl for frontends, security criteria for auth stories, pagination for list endpoints), and write the fixed file back.
+If yes, update `.ralph/prd.json`:
+- Add missing sign patterns to relevant story `constraints` or `acceptanceCriteria`
+- Fix structural issues per PRD best practices
+- Write the fixed file back
 
 ## Notes
 
-- This is the same validation that runs automatically at `ralph run` startup
+- This is the same structural validation that runs automatically at `ralph run` startup
 - `--dry-run` skips auto-fix so you have control over what changes
 - Custom checks in `.ralph/checks/prd/` are also evaluated
+- Signs cross-referencing catches patterns that structural validation can't
 - Run this before `ralph run` to catch and fix issues interactively

package/.claude/skills/tour/SKILL.md

@@ -337,7 +337,7 @@ Quick Reference
 ───────────────
 
 Workflow:
-  /idea [feature]       Brainstorm → PRD
+  /prd [feature]        Brainstorm → PRD
   npx ralph run         Execute autonomously
   npx ralph status      Check progress
   npx ralph stop        Stop after current story
@@ -354,4 +354,4 @@ Other:
   /vibe-help            Full cheatsheet
 ```
 
-Say: "You're all set! Run `/idea [your next feature]` to get started."
+Say: "You're all set! Run `/prd [your next feature]` to get started."

package/.claude/skills/vibe-help/SKILL.md

@@ -11,7 +11,7 @@ Print this cheatsheet for the user. Do not add any commentary or explanation.
 ## The Loop
 
 ```
-/idea [feature]          brainstorm & generate PRD
+/prd [feature]           brainstorm & generate PRD
 npx ralph run            autonomous coding loop (live activity feed)
 npx ralph run --quiet    same, but suppress activity feed
 npx ralph status         check progress

package/.claude/skills/vibe-list/SKILL.md

@@ -12,8 +12,8 @@ Print this complete reference for the user. Do not add any commentary.
 
 | Command | Description |
 |---------|-------------|
-| `/idea [feature]` | Brainstorm in plan mode, generate PRD for Ralph |
-| `/sign` | Add a learned pattern for Ralph to remember |
+| `/prd [feature]` | Brainstorm feature, generate executable PRD for Ralph |
+| `/sign`| Add a learned pattern for Ralph to remember |
 | `/my-dna` | Set up your personal style preferences |
 | `/vibe-check` | Audit code quality before shipping |
 | `/review` | Code review with OWASP security checks |
@@ -78,7 +78,7 @@ Print this complete reference for the user. Do not add any commentary.
 ## The Loop
 
 ```
-/idea [feature]          Brainstorm → PRD
+/prd [feature]           Brainstorm → PRD
 npx ralph run            Autonomous coding
 npx ralph status         Check progress
 npx ralph stop           Stop after current story
@@ -88,10 +88,10 @@ npx ralph stop           Stop after current story
 
 ## Slash Command Details
 
-### /idea [feature description]
-Brainstorm in plan mode, explore codebase, ask clarifying questions.
-- Writes idea to `docs/ideas/{feature}.md`
-- On approval, splits into PRD stories
+### /prd [feature description]
+Brainstorm feature, explore codebase, ask clarifying questions.
+- Accepts a description, idea file (`docs/ideas/{name}.md`), or plan file (`docs/plans/{name}.md`)
+- Splits into executable PRD stories
 - Writes to `.ralph/prd.json`
 
 ### /review [file or selection]
@@ -194,7 +194,7 @@ npx ralph unsign "camelCase"
 
 CLAUDE.md            # Project standards (shared with team)
 PROMPT.md            # Base prompt for Ralph sessions
-docs/ideas/          # Brainstorm outputs from /idea
+docs/ideas/          # Brainstorm outputs from /prd
 
 # Global files (your home directory)
 ~/.claude/

package/README.md

@@ -12,31 +12,33 @@ You describe what you want to build. Claude Code writes a PRD (Product Requireme
 
 ```
 ┌──────────────────────────────────────────────────────────────────────────────────┐
-│  TERMINAL 1: Claude CLI                │  TERMINAL 2: Execute                    │
+│  TERMINAL 1: Plan & Generate           │  TERMINAL 2: Execute                    │
 ├────────────────────────────────────────┼─────────────────────────────────────────┤
 │                                        │                                         │
 │  claude --dangerously-skip-permissions │  npx agentic-loop run                   │
 │                                        │                                         │
-│  PLAN FEATURES                         │  ┌─ prd-check (once) ───────────────┐   │
-│  /idea 'your feature or bugfix'        │  │ Validate all stories upfront     │   │
-│  → Claude asks questions               │  │ Auto-fix missing test steps      │   │
-│  → Explores codebase                   │  └──────────────────────────────────┘   │
-│  → Generates PRD                       │            ↓                            │
-│                                        │  ┌─ loop (per story) ───────────────┐   │
-│  ENHANCE AS YOU LEARN                  │  │                                  │   │
-│  → Add signs when Ralph repeats        │  │ Read prd.json → get next story   │   │
-│    the same mistake                    │  │ Load PROMPT.md, signs, config    │   │
-│  → Tune timeouts, retries, checks      │  │ Load last_failure.txt (if retry) │   │
-│  → Refine test commands for your       │  │ Build prompt with full context   │   │
-│    stack                               │  │ Spawn Claude → write code        │   │
-│                                        │  │                                  │   │
-│  (OPTIONAL) CUSTOMIZE YOUR LOOP        │  │ code-check:                      │   │
-│  /my-dna      → your coding style      │  │   [1] Lint                       │   │
-│  /styleguide  → UI consistency         │  │   [2] Tests                      │   │
+│  THE PIPELINE                          │  ┌─ prd-check (once) ───────────────┐   │
+│  1. Plan mode                          │  │ Validate all stories upfront     │   │
+│     → Think through the feature        │  │ Auto-fix missing test steps      │   │
+│     → Claude explores codebase         │  └──────────────────────────────────┘   │
+│     → Plan saved to docs/plans/        │            ↓                            │
+│                                        │                                         │
+│  2. /prd plans/my-feature              │  ┌──────────────────────────────────┐   │
+│     → Hardening questions              │  │ Read prd.json → get next story   │   │
+│     → Generates .ralph/prd.json        │  │ Load PROMPT.md, signs, config    │   │
+│                                        │  │ Load last_failure.txt (if retry) │   │
+│  3. /prd-check                         │  │ Build prompt with full context   │   │
+│     → Validate stories                 │  │ Spawn Claude → write code        │   │
+│     → Cross-ref signs                  │  │                                  │   │
+│     → Auto-fix issues                  │  │ code-check:                      │   │
+│                                        │  │   [1] Lint                       │   │
+│  ENHANCE AS YOU LEARN                  │  │   [2] Tests                      │   │
 │  /sign        → teach patterns         │  │   [3] PRD test steps             │   │
-│  config.json  → tune your setup        │  │   [4] API smoke                  │   │
-│                                        │  │   [5] Frontend smoke             │   │
-│                                        │  │                                  │   │
+│  /my-dna      → your coding style      │  │   [4] API smoke                  │   │
+│  /styleguide  → UI consistency         │  │   [5] Frontend smoke             │   │
+│  /color       → terminal tint          │  │                                  │   │
+│  /tab-rename  → name your tabs         │  │                                  │   │
+│  config.json  → tune your setup        │  │                                  │   │
 │                                        │  │ Pass → commit, next story        │   │
 │                                        │  │ Fail → save to last_failure.txt, │   │
 │                                        │  │        retry                     │   │
@@ -45,10 +47,10 @@ You describe what you want to build. Claude Code writes a PRD (Product Requireme
 └────────────────────────────────────────┴─────────────────────────────────────────┘
 ```
 
-**Terminal 1** is where you shape *what* gets built and *how* Ralph builds it.
-**Terminal 2** is where Ralph executes autonomously.
+**Terminal 1** is where you plan and generate. Plan mode lets you think through a feature with Claude before committing to code. `/prd` turns that plan into executable stories. `/prd-check` validates them.
+**Terminal 2** is where Ralph executes autonomously — coding, testing, and committing each story in a loop.
 
-Your loop gets smarter over time. When Ralph struggles with something, add a sign. When tests flake, tune the config. The customization never really stops—it's how you make Ralph work for *your* project.
+The loop gets smarter over time. When Ralph struggles with something, teach it with `/sign`. Tune timeouts and checks in `config.json`. Capture your coding style with `/my-dna`.
 
 ---
 
@@ -61,22 +63,29 @@ npm install agentic-loop
 npx agentic-loop setup
 ```
 
-**Terminal 1 - Claude Code:**
+**Terminal 1 — Plan and generate with Claude:**
 ```bash
 claude --dangerously-skip-permissions
-/tour                    # Guided walkthrough (recommended first time)
-/idea 'your feature'     # Generate a PRD
+
+# 1. Use plan mode to think through your feature
+#    Claude explores the codebase, you discuss, plan saved to docs/plans/
+
+# 2. Turn the plan into executable stories
+/prd plans/my-feature
+
+# 3. Validate before running
+/prd-check
 ```
 
-**Terminal 2 - Ralph Loop:**
+**Terminal 2 — Run the loop:**
 ```bash
-npx agentic-loop run         # Execute PRDs autonomously
+npx agentic-loop run         # Execute PRDs autonomously (spins up claude -p)
 npx agentic-loop run --quiet # Same, but suppress activity feed
 ```
 
-Ralph shows a live activity feed as it works — what files it's reading, what code it's writing, and why. Use `--quiet` to suppress it.
+Ralph shows a live activity feed as it works — what files it's reading, what code it's writing, and why. Use `--quiet` to suppress it. On macOS Terminal.app, Ralph tints the terminal background dark teal so you can tell the two terminals apart at a glance — the original color is restored when the loop ends.
 
-> **Tip:** Use two terminals. Plan with Claude in one, run Ralph in the other.
+> **Tip:** Plan first, then generate. Use plan mode to explore and think, `/prd` to create stories, `/prd-check` to validate, and `ralph run` to execute.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentic-loop",
-  "version": "3.22.1",
+  "version": "3.26.0",
   "description": "Autonomous AI coding loop - PRD-driven development with Claude Code",
   "author": "Allie Jones <allie@allthrive.ai>",
   "license": "MIT",

package/ralph/hooks/install.sh

@@ -108,70 +108,54 @@ if [[ "$FORCE" != "true" ]] && jq -e '.hooks' "$SETTINGS_FILE" > /dev/null 2>&1;
   fi
 fi
 
-# Build hooks config with actual path
-HOOKS_CONFIG=$(cat <<EOF
-{
-  "PostToolUse": [
-    {
-      "matcher": "Edit|Write",
-      "hooks": [
-        {
-          "type": "command",
-          "command": "$SCRIPT_DIR/warn-debug.sh",
-          "timeout": 5
-        },
-        {
-          "type": "command",
-          "command": "$SCRIPT_DIR/warn-secrets.sh",
-          "timeout": 5
-        },
-        {
-          "type": "command",
-          "command": "$SCRIPT_DIR/warn-urls.sh",
-          "timeout": 5
-        },
-        {
-          "type": "command",
-          "command": "$SCRIPT_DIR/warn-empty-catch.sh",
-          "timeout": 5
-        }
-      ]
-    },
-    {
-      "matcher": "*",
-      "hooks": [
-        {
-          "type": "command",
-          "command": "$SCRIPT_DIR/log-tools.sh",
-          "timeout": 3
-        }
-      ]
-    }
-  ],
-  "SessionStart": [
-    {
-      "hooks": [
-        {
-          "type": "command",
-          "command": "$SCRIPT_DIR/inject-context.sh",
-          "timeout": 5
-        }
-      ]
-    }
-  ],
-  "Stop": [
-    {
-      "hooks": [
-        {
-          "type": "command",
-          "command": "$SCRIPT_DIR/save-learnings.sh",
-          "timeout": 10
-        }
-      ]
-    }
-  ]
+# Wrap hook path with existence check so missing files don't produce errors
+_safe_cmd() {
+  local path="$1"
+  printf 'if [ -f "%s" ]; then "%s"; else echo '"'"'{"continue": true}'"'"'; fi' "$path" "$path"
 }
-EOF
+
+# Build hooks config using jq for proper JSON escaping
+HOOKS_CONFIG=$(jq -n \
+  --arg warn_debug "$(_safe_cmd "$SCRIPT_DIR/warn-debug.sh")" \
+  --arg warn_secrets "$(_safe_cmd "$SCRIPT_DIR/warn-secrets.sh")" \
+  --arg warn_urls "$(_safe_cmd "$SCRIPT_DIR/warn-urls.sh")" \
+  --arg warn_empty_catch "$(_safe_cmd "$SCRIPT_DIR/warn-empty-catch.sh")" \
+  --arg log_tools "$(_safe_cmd "$SCRIPT_DIR/log-tools.sh")" \
+  --arg inject_context "$(_safe_cmd "$SCRIPT_DIR/inject-context.sh")" \
+  --arg save_learnings "$(_safe_cmd "$SCRIPT_DIR/save-learnings.sh")" \
+  '{
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {"type": "command", "command": $warn_debug, "timeout": 5},
+          {"type": "command", "command": $warn_secrets, "timeout": 5},
+          {"type": "command", "command": $warn_urls, "timeout": 5},
+          {"type": "command", "command": $warn_empty_catch, "timeout": 5}
+        ]
+      },
+      {
+        "matcher": "*",
+        "hooks": [
+          {"type": "command", "command": $log_tools, "timeout": 3}
+        ]
+      }
+    ],
+    "SessionStart": [
+      {
+        "hooks": [
+          {"type": "command", "command": $inject_context, "timeout": 5}
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {"type": "command", "command": $save_learnings, "timeout": 10}
+        ]
+      }
+    ]
+  }'
 )
 
 # Merge hooks into settings

package/ralph/init.sh

@@ -13,7 +13,7 @@ ralph_init() {
   echo "Initializing ralph..."
 
   # Create directory structure
-  mkdir -p "$RALPH_DIR/archive" "$RALPH_DIR/screenshots"
+  mkdir -p "$RALPH_DIR/archive" "$RALPH_DIR/screenshots" "$RALPH_DIR/hooks"
 
   # Detect project type and generate appropriate config
   local project_type
@@ -68,7 +68,7 @@ ralph_init() {
   echo "Next steps:"
   echo "  1. Review .ralph/config.json (test credentials, checks, etc.)"
   echo "  2. Generate PRD:"
-  echo "     - Thorough: /idea 'feature description' (brainstorm + architecture + scalability)"
+  echo "     - Thorough: /prd 'feature description' (brainstorm + architecture + scalability)"
   echo "     - Quick:    ralph prd 'feature description' (basic PRD)"
   echo "  3. Start loop: ralph run"
 }
@@ -677,7 +677,7 @@ What is this?
     commands without asking permission each time. This enables fluid,
     uninterrupted collaboration while you brainstorm and refine ideas.
 
-    Use /idea to brainstorm big features. Claude saves your ideas to
+    Use /prd to brainstorm big features. Claude saves your ideas to
     docs/ideas/, then breaks them into small, executable PRDs.
 
   Terminal 2 - Ralph (autonomous execution):
@@ -690,7 +690,7 @@ What is this?
 Quick Start:
   1. npx agentic-loop setup
   2. Terminal 1: claude --dangerously-skip-permissions
-  3. In Claude: /idea "your feature description"
+  3. In Claude: /prd "your feature description"
   4. Terminal 2: npx agentic-loop run
   5. Monitor Terminal 2 - it should be autonomous. If issues come up,
      stop the loop (Ctrl+C) and paste the errors into Terminal 1.
@@ -729,12 +729,12 @@ Commands:
   help                    Show this help message
 
 PRD Generation:
-  /idea <description>           Thorough brainstorm (in Claude Code)
+  /prd <description>            Thorough brainstorm (in Claude Code)
   npx agentic-loop prd <notes>     Quick PRD generation
 
 Examples:
   npm install agentic-loop && npx agentic-loop setup
-  /idea "Add user authentication with OAuth"
+  /prd "Add user authentication with OAuth"
   npx agentic-loop prd "Add a contact form"
   npx agentic-loop run
   npx agentic-loop run --max 10

package/ralph/loop.sh

@@ -2,6 +2,107 @@
 # shellcheck shell=bash
 # loop.sh - The autonomous development loop
 
+# Check for newer version on npm and offer to update
+check_for_updates() {
+  local cache_file="$RALPH_DIR/.update_cache"
+
+  # Skip if checked recently (once per day)
+  if [[ -f "$cache_file" ]]; then
+    local cached_time
+    read -r cached_time _ < "$cache_file"
+    local now
+    now=$(date +%s)
+    if [[ $(( now - cached_time )) -lt $UPDATE_CHECK_TTL_SECONDS ]]; then
+      return 0
+    fi
+  fi
+
+  local latest
+  latest=$(timeout 5 npm view agentic-loop version --json 2>/dev/null | tr -d '"' || echo "")
+  # Fall back to gtimeout on macOS if timeout isn't available
+  if [[ -z "$latest" ]] && command -v gtimeout &>/dev/null; then
+    latest=$(gtimeout 5 npm view agentic-loop version --json 2>/dev/null | tr -d '"' || echo "")
+  fi
+
+  # Write cache regardless of result (don't retry on failure)
+  echo "$(date +%s) $latest" > "$cache_file"
+
+  # If registry unreachable or empty, skip silently
+  [[ -z "$latest" ]] && return 0
+
+  # Compare versions — if already current or newer, skip
+  if [[ "$RALPH_VERSION" == "$latest" ]]; then
+    return 0
+  fi
+
+  # Simple semver comparison: split on dots and compare numerically
+  local IFS='.'
+  # shellcheck disable=SC2206  # Intentional word-split on IFS='.'
+  local -a current_parts=($RALPH_VERSION)
+  # shellcheck disable=SC2206
+  local -a latest_parts=($latest)
+
+  local i
+  for i in 0 1 2; do
+    local c="${current_parts[$i]:-0}"
+    local l="${latest_parts[$i]:-0}"
+    if [[ "$c" -gt "$l" ]]; then
+      return 0  # Current is ahead (dev build)
+    elif [[ "$c" -lt "$l" ]]; then
+      break  # Current is behind — needs update
+    fi
+  done
+
+  echo ""
+  print_warning "Update available: v$RALPH_VERSION → v$latest"
+
+  # Detect install method to determine update command
+  local update_cmd=""
+  local script_path
+  script_path="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+
+  if [[ "$script_path" == *"node_modules/agentic-loop"* ]]; then
+    # Local install
+    update_cmd="npm update agentic-loop"
+  elif npm list -g agentic-loop --depth=0 &>/dev/null 2>&1; then
+    # Global install
+    update_cmd="npm update -g agentic-loop"
+  else
+    # npx or unknown — use npx with latest
+    update_cmd="npx agentic-loop@latest"
+  fi
+
+  read -r -p "  Update now and restart? [Y/n] " response
+  if [[ "$response" =~ ^[Nn] ]]; then
+    echo "  Skipping update. Run: $update_cmd"
+    echo ""
+    return 0
+  fi
+
+  echo "  Updating..."
+  if [[ "$update_cmd" == "npx agentic-loop@latest" ]]; then
+    # For npx users, clear the cache so next npx call fetches latest
+    local npx_cache
+    npx_cache=$(npm config get cache 2>/dev/null || echo "$HOME/.npm")
+    rm -rf "${npx_cache}/_npx" 2>/dev/null || true
+    print_success "  npx cache cleared — restarting with v$latest..."
+    echo ""
+    exec npx agentic-loop@latest run "$@"
+  else
+    if $update_cmd 2>&1 | tail -3; then
+      print_success "  Updated to v$latest — restarting..."
+      echo ""
+      # Re-exec ralph.sh with "run" + original args
+      local ralph_bin
+      ralph_bin="$(cd "$(dirname "${BASH_SOURCE[0]}")/../bin" && pwd)/ralph.sh"
+      exec "$ralph_bin" run "$@"
+    else
+      print_warning "  Update failed. Run manually: $update_cmd"
+      echo ""
+    fi
+  fi
+}
+
 # Pre-loop checks to catch common issues before wasting iterations
 preflight_checks() {
   echo ""
@@ -621,6 +722,9 @@ _docker_safety_warning() {
 }
 
 run_loop() {
+  # Save original args for update restart
+  local _original_args=("$@")
+
   # PID of the currently running Claude pipeline (used by trap to kill it)
   _CLAUDE_PIPELINE_PID=""
 
@@ -630,6 +734,8 @@ run_loop() {
   # pipeline in a background subshell and `wait`ing for it, which lets the trap
   # fire immediately. The trap kills the subshell, touches .stop, then exits.
   trap '
+    restore_tab_title
+    restore_terminal_bg
     echo ""
     print_warning "Ctrl+C received — stopping loop..."
     [[ -n "$_CLAUDE_PIPELINE_PID" ]] && kill -TERM "$_CLAUDE_PIPELINE_PID" 2>/dev/null
@@ -638,6 +744,18 @@ run_loop() {
     exit 130
   ' INT
 
+  # Tint terminal background so Ralph's terminal is visually distinct
+  local tint_color
+  tint_color=$(get_config '.terminalTint' "#1a2e2e")
+  if [[ "$tint_color" != "off" ]]; then
+    set_terminal_bg "$tint_color"
+  fi
+
+  # Set tab title to project name so the Ralph terminal is identifiable
+  local project_name
+  project_name=$(basename "$(pwd)")
+  set_tab_title "Ralph: $project_name"
+
   local max_iterations=""  # No cap by default — per-story circuit breaker is the safety net
   local specific_story=""
   local fast_mode=false
@@ -675,6 +793,9 @@ run_loop() {
   # Validate prerequisites
   check_dependencies
 
+  # Check for newer version on npm (once per day, non-blocking if offline)
+  check_for_updates "${_original_args[@]}"
+
   # Warn if no Docker compose file (safety net for autonomous execution)
   _docker_safety_warning
 
@@ -720,9 +841,9 @@ run_loop() {
       echo ""
       echo "  2. Inside Claude, type:"
       echo ""
-      echo "       /idea \"your feature description\""
+      echo "       /prd \"your feature description\""
       echo ""
-      echo "  Note: /idea is a Claude skill — it only works inside an active"
+      echo "  Note: /prd is a Claude skill — it only works inside an active"
       echo "  Claude session, not from your regular terminal."
       echo ""
       echo "  See Step 4 of the Getting Started guide:"
@@ -938,6 +1059,9 @@ run_loop() {
     passed_stories=$(jq '[.stories[] | select(.passes==true)] | length' "$RALPH_DIR/prd.json")
     current_num=$((passed_stories + 1))
 
+    # Update tab title with current story
+    set_tab_title "Ralph: $story — $story_title"
+
     # Display dynamic banner (truncate long text to fit box)
     local max_width=53
     local display_title="$story_title"
@@ -1700,6 +1824,6 @@ archive_feature() {
   echo "All stories passed! PRD kept at: $RALPH_DIR/prd.json"
   echo ""
   echo "Next:"
-  echo "  Start a Claude Code session and run /idea to brainstorm your next feature."
+  echo "  Start a Claude Code session and run /prd to brainstorm your next feature."
   echo "  ralph status            # See completed stories"
 }