@pennyfarthing/core 11.2.1 → 11.2.2

package/README.md

@@ -1,6 +1,6 @@
 # Pennyfarthing
 
-**v11.2.1** | *The outer loop goes once, the inner loop goes many times.*
+**v11.2.2** | *The outer loop goes once, the inner loop goes many times.*
 
 <img src="pennyfarthing.png" alt="Pennyfarthing Logo" width="75" style="float:left; margin:10px">
 
@@ -45,35 +45,61 @@ The 98 persona themes (Discworld, Star Trek, Breaking Bad, etc.) are instruments
 
 ## Quick Start
 
+### Install
+
 ```bash
 cd your-project
 
-# Install CLI
+# Install core package
 npm install --save-dev @pennyfarthing/core
 
-# Initialize (creates symlinks)
+# Initialize project (creates .pennyfarthing/, .claude/ symlinks)
 npx pennyfarthing init
 
 # Verify installation
 npx pennyfarthing doctor
 
-# Start working (in Claude Code)
-/new-work
+# Start working (inside Claude Code)
+/pf-work
 ```
 
-### Optional: Visual Terminal
+### Choose How to Work
+
+Pennyfarthing works in any terminal, but optional dashboards give you real-time visibility into what agents are doing. Pick the mode that fits your workflow:
+
+| I want to... | Mode | Command |
+|--------------|------|---------|
+| Just use agents in my terminal | **CLI only** | `claude` (no dashboard needed) |
+| See dashboards in my browser | **BikeRack GUI** | `just gui` + `just claude` |
+| Stay fully in the terminal | **BikeRack TUI** | `just tui` + `just claude` |
+| One command, everything | **BikeRack all-in-one** | `pf bikerack start` |
+| Full desktop app with embedded terminal | **Cyclist** | `npx pennyfarthing cyclist` |
+
+```mermaid
+graph LR
+    subgraph "CLI Only"
+        A["claude"] --> B["Agents work in your terminal<br/>No dashboard"]
+    end
+
+    subgraph "BikeRack (dashboard + your terminal)"
+        C["just gui / just tui"] --> D["WheelHub Server"]
+        E["just claude"] --> D
+        D --> F["Dashboard panels<br/>(browser or TUI)"]
+    end
+
+    subgraph "Cyclist (all-in-one desktop app)"
+        G["pennyfarthing cyclist"] --> H["Electron app<br/>Embedded terminal + panels"]
+    end
+```
 
-```bash
-# Install Cyclist (includes portraits)
-npm install --save-dev @pennyfarthing/cyclist
+> **See the full [BikeRack Guide](pennyfarthing-dist/guides/bikerack.md)** for detailed quickstart paths, OTEL telemetry setup, and command reference.
 
-# Launch
-npx pennyfarthing cyclist
-```
+## Visual Dashboards
 
-## Cyclist Visual Terminal
+Whether you use Cyclist or BikeRack, you get the same 17 dashboard panels showing real-time agent activity:
 
-Cyclist is an Electron-based IDE built on React 19, Tailwind v4, and Dockview. It wraps Claude Code with a rich panel system and workflow controls.
+<!-- TODO: Screenshot of Cyclist with multiple panels visible -->
+<!-- ![Cyclist Dashboard](docs/images/cyclist-dashboard.png) -->
 
 ### Panels
 
@@ -81,49 +107,83 @@ All panels are draggable, floatable, and splittable:
 
 | Panel | Purpose |
 |-------|---------|
-| **Message** | Conversation stream (always visible) |
+| **Message** | Conversation stream (Cyclist only) |
 | **Sprint** | Current sprint stories and progress |
 | **Progress** | At-a-glance story dashboard |
-| **BikeLane** | Stepped workflow state and navigation |
+| **BikeLane** | Workflow phase state and navigation |
 | **AC** | Acceptance criteria checklist with progress |
-| **Acceptance Criteria** | Story ACs with pass/fail tracking |
-| **Changed** | Files added or modified during the session |
-| **Diffs** | Git-based diff viewer for current changes |
-| **Git** | Branch management and git operations |
+| **Changed** | Files modified during the session |
+| **Diffs** | Git diff viewer for current changes |
+| **Git** | Branch management and status |
 | **Todo** | Task list tracking |
-| **Audit Log** | Timestamped action history |
-| **Settings** | Permission mode, relay mode, bell mode toggles |
+| **Audit Log** | Timestamped tool use history |
+| **Workflow** | Workflow navigation and status |
+| **Hotspots** | Codebase health — dead code, complexity |
+| **Settings** | Permission mode, relay mode, bell mode |
 | **Debug** | Prime context inspection with token counts |
 | **Background** | Background job monitoring |
-| **Workflow** | Workflow navigation and status |
-| **Hotspots** | Codebase health — dead code, complexity, dependencies |
 
-### Tool Visualization
+<!-- TODO: Screenshot of BikeRack TUI -->
+<!-- ![BikeRack TUI](docs/images/bikerack-tui.png) -->
 
-Cyclist renders tool use as human-readable summaries instead of raw JSON. Consecutive identical tool calls are stacked, and results are collapsible.
+### Cyclist vs BikeRack
 
-### Workflow Modes
+| | Cyclist | BikeRack |
+|---|---------|----------|
+| **Runtime** | Electron desktop app | Node.js server + browser/TUI |
+| **Terminal** | Embedded (node-pty) | Your own terminal |
+| **Conversation UI** | Built-in MessagePanel | Not included (by design) |
+| **Dashboard panels** | 17 Dockview panels | Same 17 panels |
+| **OTEL telemetry** | Automatic | Via `just claude` or `pf bikerack start` |
+| **Install** | `npm i @pennyfarthing/cyclist` | Included in `@pennyfarthing/core` |
 
-| Mode | Description |
-|------|-------------|
-| **Permission Mode** | `plan` / `manual` / `accept` — controls how much Claude can do without approval |
-| **Relay Mode** | Automatic agent handoffs — detects `CYCLIST:HANDOFF` markers and runs the next agent |
-| **Bell Mode** | Queue messages while Claude works — injected at next tool execution via hooks |
+### Architecture
 
-### Agent Portraits
+Both Cyclist and BikeRack are wrappers around **WheelHub**, the shared Express/WebSocket server that serves API endpoints, WebSocket channels, and the OTLP telemetry receiver:
 
-Each of the 319 persona characters across 29 themes has a unique portrait displayed in the conversation stream, making multi-agent workflows visually distinct.
+```mermaid
+graph TB
+    subgraph "Cyclist (Electron)"
+        C["Electron + React UI"]
+    end
+    subgraph "BikeRack (CLI)"
+        BR["Node.js server"]
+    end
 
-### BikeRack (CLI-First Dashboard)
+    C --> WH["WheelHub<br/>(shared server)"]
+    BR --> WH
 
-For developers who prefer Claude Code in their own terminal, BikeRack runs WheelHub separately and serves panels in a browser:
+    C -- "writes" --> CP[".cyclist-port"]
+    BR -- "writes" --> BP[".bikerack-port"]
 
-```bash
-pf bikerack start      # Launch BikeRack + Claude CLI
-just bikerack          # Same, via just recipe
+    WH --> API["/api/* endpoints"]
+    WH --> WS["/ws/* channels"]
+    WH --> OTLP["/v1/* OTLP receiver"]
 ```
 
-BikeRack provides the same panels as Cyclist without the conversation UI. Panels receive data via OTEL telemetry and file watchers.
+> **See [Cyclist Architecture](docs/CYCLIST-ARCHITECTURE.md)** for the full component breakdown and codename glossary.
+
+### Tool Visualization
+
+<!-- TODO: Screenshot of tool call rendering -->
+<!-- ![Tool Visualization](docs/images/tool-visualization.png) -->
+
+Cyclist and BikeRack render tool use as human-readable summaries instead of raw JSON. Consecutive identical tool calls are stacked, and results are collapsible.
+
+### Agent Portraits
+
+<!-- TODO: Screenshot of agent portrait in conversation -->
+<!-- ![Agent Portrait](docs/images/agent-portrait.png) -->
+
+Each of the 319 persona characters across 29 themes has a unique portrait displayed in the conversation stream, making multi-agent workflows visually distinct.
+
+### Workflow Modes
+
+| Mode | Description |
+|------|-------------|
+| **Permission Mode** | `plan` / `manual` / `accept` — controls how much Claude can do without approval |
+| **Relay Mode** | Automatic agent handoffs — detects `CYCLIST:HANDOFF` markers and runs the next agent |
+| **Bell Mode** | Queue messages while Claude works — injected at next tool execution via hooks |
 
 ## Prime Context System
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pennyfarthing/core",
-  "version": "11.2.1",
+  "version": "11.2.2",
   "description": "Claude Code agent framework with TDD workflow and persona system",
   "type": "module",
   "bin": {

package/packages/core/dist/cli/commands/doctor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/doctor.ts"],"names":[],"mappings":"AAwBA,UAAU,aAAa;IACrB,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC;IACjC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;CAClB;AAED,wBAAsB,aAAa,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CA8HzE;AAu3DD;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,WAAW,EAAE,MAAM,GAAG,WAAW,EAAE,CA+JnE;AAED;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CAAC,WAAW,EAAE,MAAM,GAAG,WAAW,CAkF1E;AAqFD;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,WAAW,EAAE,MAAM,GAAG,WAAW,EAAE,CAsIlE"}
+{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/doctor.ts"],"names":[],"mappings":"AAwBA,UAAU,aAAa;IACrB,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC;IACjC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;CAClB;AAED,wBAAsB,aAAa,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CA8HzE;AAm+DD;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,WAAW,EAAE,MAAM,GAAG,WAAW,EAAE,CA+JnE;AAED;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CAAC,WAAW,EAAE,MAAM,GAAG,WAAW,CAkF1E;AAqFD;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,WAAW,EAAE,MAAM,GAAG,WAAW,EAAE,CAsIlE"}

package/packages/core/dist/cli/commands/doctor.js

@@ -196,7 +196,7 @@ function checkCoreFiles(projectRoot, manifest) {
  * Check commands and skills are properly copied (not symlinked) and up to date.
  * Commands and skills are file copies since v11.3.0 to avoid node_modules drift.
  */
-function checkCommandsAndSkills(projectRoot, nodeModulesPath) {
+function checkCommandsAndSkills(projectRoot, _nodeModulesPath) {
     const results = [];
     // Use assetsPath for source resolution (correct pf-* prefix in dogfood)
     let assetsPath = null;
@@ -530,6 +530,9 @@ function checkUserFiles(projectRoot) {
         // Check SessionStart hooks are configured (critical for PROJECT_ROOT)
         const hookCheck = checkSessionStartHooks(projectRoot, installationType);
         results.push(hookCheck);
+        // Check OTEL auto-configuration (WheelHub auto-start + telemetry env vars)
+        const otelCheck = checkOtelAutoStart(projectRoot, installationType);
+        results.push(otelCheck);
         // Check auto-load-sm hook is configured (auto-invokes /sm on new sessions)
         const autoLoadSmCheck = checkAutoLoadSmHook(projectRoot);
         results.push(autoLoadSmCheck);
@@ -654,7 +657,7 @@ function checkSessionStartHooks(projectRoot, installationType) {
         const hasSessionStartHook = settings.hooks.SessionStart.some((entry) => {
             if (typeof entry === 'object' && entry !== null) {
                 const hookEntry = entry;
-                return hookEntry.hooks?.some(h => h.command?.includes('pf hooks session-start') || h.command?.includes('session-start.sh'));
+                return hookEntry.hooks?.some(h => h.command?.includes('pf.sh hooks session-start') || h.command?.includes('pf hooks session-start') || h.command?.includes('session-start.sh'));
             }
             return false;
         });
@@ -682,6 +685,96 @@ function checkSessionStartHooks(projectRoot, installationType) {
         };
     }
 }
+/**
+ * Check that session-start hook uses `pf hooks session-start` (Python version)
+ * which handles WheelHub auto-start + OTEL env var configuration.
+ * Legacy .sh hooks only set 2 of 5 required OTEL vars, breaking telemetry.
+ */
+function checkOtelAutoStart(projectRoot, installationType) {
+    const settingsPath = join(projectRoot, '.claude/settings.local.json');
+    try {
+        const settings = JSON.parse(readFileSync(settingsPath, 'utf8'));
+        if (!settings.hooks?.SessionStart) {
+            return {
+                name: 'settings/otel-auto-start',
+                status: 'warn',
+                detail: 'No SessionStart hooks — WheelHub auto-start and OTEL not configured',
+            };
+        }
+        // Check if `pf hooks session-start` is used (Python version with full OTEL support)
+        const hasPfHooksSessionStart = settings.hooks.SessionStart.some((entry) => {
+            if (typeof entry === 'object' && entry !== null) {
+                const hookEntry = entry;
+                return hookEntry.hooks?.some(h => h.command?.includes('pf.sh hooks session-start') || h.command?.includes('pf hooks session-start'));
+            }
+            return false;
+        });
+        if (hasPfHooksSessionStart) {
+            return {
+                name: 'settings/otel-auto-start',
+                status: 'pass',
+                detail: undefined,
+            };
+        }
+        // Check if using legacy .sh (only sets 2 of 5 OTEL vars)
+        const hasLegacySh = settings.hooks.SessionStart.some((entry) => {
+            if (typeof entry === 'object' && entry !== null) {
+                const hookEntry = entry;
+                return hookEntry.hooks?.some(h => h.command?.includes('session-start.sh'));
+            }
+            return false;
+        });
+        if (hasLegacySh) {
+            return {
+                name: 'settings/otel-auto-start',
+                status: 'warn',
+                detail: 'Using legacy session-start.sh — missing WheelHub auto-start and 3 OTEL env vars. Migrate to `pf hooks session-start`',
+                fix: () => {
+                    migrateSessionStartToPfHooks(projectRoot);
+                },
+            };
+        }
+        return {
+            name: 'settings/otel-auto-start',
+            status: 'warn',
+            detail: 'session-start hook not found — WheelHub auto-start and OTEL not configured',
+            fix: () => {
+                addSessionStartHooks(projectRoot, installationType);
+            },
+        };
+    }
+    catch {
+        return {
+            name: 'settings/otel-auto-start',
+            status: 'warn',
+            detail: 'Could not parse settings.local.json',
+        };
+    }
+}
+/**
+ * Migrate legacy session-start.sh hooks to `pf hooks session-start`
+ */
+function migrateSessionStartToPfHooks(projectRoot) {
+    const settingsPath = join(projectRoot, '.claude/settings.local.json');
+    try {
+        const settings = JSON.parse(readFileSync(settingsPath, 'utf8'));
+        if (Array.isArray(settings.hooks?.SessionStart)) {
+            for (const entry of settings.hooks.SessionStart) {
+                if (typeof entry === 'object' && entry !== null && Array.isArray(entry.hooks)) {
+                    for (const h of entry.hooks) {
+                        if (h.command?.includes('session-start.sh')) {
+                            h.command = '"$CLAUDE_PROJECT_DIR"/.pennyfarthing/scripts/core/pf.sh hooks session-start';
+                        }
+                    }
+                }
+            }
+        }
+        writeFileSync(settingsPath, JSON.stringify(settings, null, 2), 'utf8');
+    }
+    catch {
+        // Silent fail — doctor will re-report on next run
+    }
+}
 /**
  * Check that auto-load-sm hook is configured in SessionStart
  * This auto-invokes /sm agent on new session start
@@ -832,7 +925,7 @@ function checkStopHook(projectRoot, installationType) {
         const hasReflectorHook = settings.hooks.Stop.some((entry) => {
             if (typeof entry === 'object' && entry !== null) {
                 const hookEntry = entry;
-                return hookEntry.hooks?.some(h => h.command?.includes('pf hooks reflector-check') || h.command?.includes('question-reflector-check'));
+                return hookEntry.hooks?.some(h => h.command?.includes('pf.sh hooks reflector-check') || h.command?.includes('pf hooks reflector-check') || h.command?.includes('question-reflector-check'));
             }
             return false;
         });
@@ -883,7 +976,7 @@ function checkContextCircuitBreaker(projectRoot, installationType) {
         const hasCircuitBreaker = settings.hooks.PreToolUse.some((entry) => {
             if (typeof entry === 'object' && entry !== null) {
                 const hookEntry = entry;
-                return hookEntry.hooks?.some(h => h.command?.includes('pf hooks context-breaker') || h.command?.includes('context-circuit-breaker'));
+                return hookEntry.hooks?.some(h => h.command?.includes('pf.sh hooks context-breaker') || h.command?.includes('pf hooks context-breaker') || h.command?.includes('context-circuit-breaker'));
             }
             return false;
         });
@@ -921,7 +1014,7 @@ function addContextCircuitBreaker(projectRoot, _installationType) {
         hooks: [
             {
                 type: 'command',
-                command: 'pf hooks context-breaker'
+                command: '"$CLAUDE_PROJECT_DIR"/.pennyfarthing/scripts/core/pf.sh hooks context-breaker'
             }
         ]
     };
@@ -1009,7 +1102,7 @@ function addSchemaValidationHook(projectRoot, _installationType) {
         hooks: [
             {
                 type: 'command',
-                command: 'pf hooks schema-validation'
+                command: '"$CLAUDE_PROJECT_DIR"/.pennyfarthing/scripts/core/pf.sh hooks schema-validation'
             }
         ]
     };
@@ -1059,7 +1152,7 @@ function checkPostToolUseHook(projectRoot, installationType) {
         const hasBellModeHook = settings.hooks.PostToolUse.some((entry) => {
             if (typeof entry === 'object' && entry !== null) {
                 const hookEntry = entry;
-                return hookEntry.hooks?.some(h => h.command?.includes('pf hooks bell-mode') || h.command?.includes('bell-mode-hook'));
+                return hookEntry.hooks?.some(h => h.command?.includes('pf.sh hooks bell-mode') || h.command?.includes('pf hooks bell-mode') || h.command?.includes('bell-mode-hook'));
             }
             return false;
         });
@@ -1098,7 +1191,7 @@ function addPostToolUseHook(projectRoot, _installationType) {
         hooks: [
             {
                 type: 'command',
-                command: 'pf hooks bell-mode'
+                command: '"$CLAUDE_PROJECT_DIR"/.pennyfarthing/scripts/core/pf.sh hooks bell-mode'
             }
         ]
     };
@@ -1148,7 +1241,7 @@ function checkSprintYamlValidationHook(projectRoot, installationType) {
         const hasSprintYamlValidation = settings.hooks.PostToolUse.some((entry) => {
             if (typeof entry === 'object' && entry !== null) {
                 const hookEntry = entry;
-                return hookEntry.hooks?.some(h => h.command?.includes('pf hooks sprint-yaml') || h.command?.includes('sprint-yaml-validation'));
+                return hookEntry.hooks?.some(h => h.command?.includes('pf.sh hooks sprint-yaml') || h.command?.includes('pf hooks sprint-yaml') || h.command?.includes('sprint-yaml-validation'));
             }
             return false;
         });
@@ -1187,7 +1280,7 @@ function addSprintYamlValidationHook(projectRoot, _installationType) {
         hooks: [
             {
                 type: 'command',
-                command: 'pf hooks sprint-yaml'
+                command: '"$CLAUDE_PROJECT_DIR"/.pennyfarthing/scripts/core/pf.sh hooks sprint-yaml'
             }
         ]
     };
@@ -1225,7 +1318,7 @@ function addStopHook(projectRoot, _installationType) {
             hooks: [
                 {
                     type: 'command',
-                    command: 'pf hooks reflector-check'
+                    command: '"$CLAUDE_PROJECT_DIR"/.pennyfarthing/scripts/core/pf.sh hooks reflector-check'
                 }
             ]
         },
@@ -1234,7 +1327,7 @@ function addStopHook(projectRoot, _installationType) {
             hooks: [
                 {
                     type: 'command',
-                    command: 'pf hooks session-stop'
+                    command: '"$CLAUDE_PROJECT_DIR"/.pennyfarthing/scripts/core/pf.sh hooks session-stop'
                 }
             ]
         }
@@ -1282,7 +1375,7 @@ function addSessionStartHooks(projectRoot, _installationType) {
             hooks: [
                 {
                     type: 'command',
-                    command: 'pf hooks session-start'
+                    command: '"$CLAUDE_PROJECT_DIR"/.pennyfarthing/scripts/core/pf.sh hooks session-start'
                 }
             ]
         },
@@ -1376,7 +1469,7 @@ function createSettingsLocalJson(projectRoot, _installationType) {
                     hooks: [
                         {
                             type: 'command',
-                            command: 'pf hooks session-start'
+                            command: '"$CLAUDE_PROJECT_DIR"/.pennyfarthing/scripts/core/pf.sh hooks session-start'
                         }
                     ]
                 },
@@ -1404,7 +1497,7 @@ function createSettingsLocalJson(projectRoot, _installationType) {
                     hooks: [
                         {
                             type: 'command',
-                            command: 'pf hooks reflector-check'
+                            command: '"$CLAUDE_PROJECT_DIR"/.pennyfarthing/scripts/core/pf.sh hooks reflector-check'
                         }
                     ]
                 },
@@ -1413,7 +1506,7 @@ function createSettingsLocalJson(projectRoot, _installationType) {
                     hooks: [
                         {
                             type: 'command',
-                            command: 'pf hooks session-stop'
+                            command: '"$CLAUDE_PROJECT_DIR"/.pennyfarthing/scripts/core/pf.sh hooks session-stop'
                         }
                     ]
                 }
@@ -1424,7 +1517,7 @@ function createSettingsLocalJson(projectRoot, _installationType) {
                     hooks: [
                         {
                             type: 'command',
-                            command: 'pf hooks bell-mode'
+                            command: '"$CLAUDE_PROJECT_DIR"/.pennyfarthing/scripts/core/pf.sh hooks bell-mode'
                         }
                     ]
                 },
@@ -1433,7 +1526,7 @@ function createSettingsLocalJson(projectRoot, _installationType) {
                     hooks: [
                         {
                             type: 'command',
-                            command: 'pf hooks sprint-yaml'
+                            command: '"$CLAUDE_PROJECT_DIR"/.pennyfarthing/scripts/core/pf.sh hooks sprint-yaml'
                         }
                     ]
                 }
@@ -1444,7 +1537,7 @@ function createSettingsLocalJson(projectRoot, _installationType) {
                     hooks: [
                         {
                             type: 'command',
-                            command: 'pf hooks pre-edit-check'
+                            command: '"$CLAUDE_PROJECT_DIR"/.pennyfarthing/scripts/core/pf.sh hooks pre-edit-check'
                         }
                     ]
                 },
@@ -1453,7 +1546,7 @@ function createSettingsLocalJson(projectRoot, _installationType) {
                     hooks: [
                         {
                             type: 'command',
-                            command: 'pf hooks schema-validation'
+                            command: '"$CLAUDE_PROJECT_DIR"/.pennyfarthing/scripts/core/pf.sh hooks schema-validation'
                         }
                     ]
                 },
@@ -1462,7 +1555,7 @@ function createSettingsLocalJson(projectRoot, _installationType) {
                     hooks: [
                         {
                             type: 'command',
-                            command: 'pf hooks context-warning'
+                            command: '"$CLAUDE_PROJECT_DIR"/.pennyfarthing/scripts/core/pf.sh hooks context-warning'
                         }
                     ]
                 },
@@ -1471,7 +1564,7 @@ function createSettingsLocalJson(projectRoot, _installationType) {
                     hooks: [
                         {
                             type: 'command',
-                            command: 'pf hooks context-breaker'
+                            command: '"$CLAUDE_PROJECT_DIR"/.pennyfarthing/scripts/core/pf.sh hooks context-breaker'
                         }
                     ]
                 },
@@ -1479,7 +1572,7 @@ function createSettingsLocalJson(projectRoot, _installationType) {
                     hooks: [
                         {
                             type: 'command',
-                            command: 'pf hooks cyclist-pretooluse'
+                            command: '"$CLAUDE_PROJECT_DIR"/.pennyfarthing/scripts/core/pf.sh hooks cyclist-pretooluse'
                         }
                     ]
                 }
@@ -1487,7 +1580,7 @@ function createSettingsLocalJson(projectRoot, _installationType) {
         },
         statusLine: {
             type: 'command',
-            command: 'pf hooks statusline'
+            command: '"$CLAUDE_PROJECT_DIR"/.pennyfarthing/scripts/core/pf.sh hooks statusline'
         }
     };
     ensureDirSync(join(projectRoot, '.claude'));
@@ -2049,7 +2142,7 @@ export function checkLegacyStatuslinePath(projectRoot) {
     const pathMatch = command.match(/(?:\"\$CLAUDE_PROJECT_DIR\"\/)?([^\s"]+)/);
     const currentPath = pathMatch ? pathMatch[1] : command;
     // Check if it's the canonical pf hooks command or the legacy .sh path
-    if (command === 'pf hooks statusline' || currentPath.includes('misc/statusline.sh') || command.includes('misc/statusline.sh')) {
+    if (command.includes('pf.sh hooks statusline') || command === 'pf hooks statusline' || currentPath.includes('misc/statusline.sh') || command.includes('misc/statusline.sh')) {
         return {
             name: 'settings/statusline-path',
             status: 'pass',
@@ -2070,7 +2163,7 @@ export function checkLegacyStatuslinePath(projectRoot) {
                     const updatedSettings = { ...settings };
                     updatedSettings.statusLine = {
                         type: 'command',
-                        command: 'pf hooks statusline'
+                        command: '"$CLAUDE_PROJECT_DIR"/.pennyfarthing/scripts/core/pf.sh hooks statusline'
                     };
                     writeFileSync(settingsPath, JSON.stringify(updatedSettings, null, 2));
                 }
@@ -2126,7 +2219,7 @@ function checkLegacyHookCommands(projectRoot) {
     }
     // Also check statusLine
     const statusLine = settings.statusLine;
-    if (statusLine?.command && statusLine.command !== 'pf hooks statusline') {
+    if (statusLine?.command && !statusLine.command.includes('pf.sh hooks statusline') && statusLine.command !== 'pf hooks statusline') {
         for (const shName of Object.keys(LEGACY_HOOK_MIGRATIONS)) {
             if (statusLine.command.includes(shName)) {
                 legacyCount++;
@@ -2148,7 +2241,7 @@ function checkLegacyHookCommands(projectRoot) {
                 }
             }
             // Migrate statusLine
-            if (statusLine?.command && statusLine.command !== 'pf hooks statusline') {
+            if (statusLine?.command && !statusLine.command.includes('pf.sh hooks statusline') && statusLine.command !== 'pf hooks statusline') {
                 for (const [shName, pfCommand] of Object.entries(LEGACY_HOOK_MIGRATIONS)) {
                     if (statusLine.command.includes(shName)) {
                         statusLine.command = pfCommand;