@pennyfarthing/core 11.2.0 → 11.2.2

package/README.md

@@ -1,6 +1,6 @@
 # Pennyfarthing
 
-**v11.2.0** | *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.0",
+  "version": "11.2.2",
   "description": "Claude Code agent framework with TDD workflow and persona system",
   "type": "module",
   "bin": {
@@ -11,6 +11,7 @@
     "packages/core/dist/",
     "pennyfarthing-dist/agents/",
     "pennyfarthing-dist/commands/",
+    "pennyfarthing-dist/gates/",
     "pennyfarthing-dist/guides/",
     "pennyfarthing-dist/output-styles/",
     "pennyfarthing-dist/personas/themes/",

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":"AAsBA,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,CA2HzE;AAsoDD;;;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;AAED;;;;;;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"}