@pennyfarthing/core 7.0.1 → 7.0.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pennyfarthing/core",
-  "version": "7.0.1",
+  "version": "7.0.2",
   "description": "Claude Code agent framework with TDD workflow and persona system",
   "type": "module",
   "bin": {
@@ -28,14 +28,6 @@
   "bugs": {
     "url": "https://github.com/1898andCo/pennyfarthing/issues"
   },
-  "scripts": {
-    "build": "pnpm -r build && ./scripts/utils/generate-skill-docs.sh",
-    "docs": "./scripts/utils/generate-skill-docs.sh",
-    "dev": "pnpm -r --parallel dev",
-    "test": "pnpm -r test",
-    "lint": "eslint 'packages/*/src/**/*.ts' --max-warnings 0",
-    "clean": "pnpm -r clean"
-  },
   "dependencies": {
     "chalk": "^5.3.0",
     "commander": "^12.1.0",
@@ -54,5 +46,12 @@
   "engines": {
     "node": ">=18.0.0"
   },
-  "packageManager": "pnpm@9.0.0"
-}
+  "scripts": {
+    "build": "pnpm -r build && ./scripts/utils/generate-skill-docs.sh",
+    "docs": "./scripts/utils/generate-skill-docs.sh",
+    "dev": "pnpm -r --parallel dev",
+    "test": "pnpm -r test",
+    "lint": "eslint 'packages/*/src/**/*.ts' --max-warnings 0",
+    "clean": "pnpm -r clean"
+  }
+}

package/pennyfarthing-dist/agents/README.md

@@ -49,7 +49,18 @@ Focus on specific repo(s), implement/test/document features.
 - **`ux-designer.md`** - UX Designer (UI design, UX)
 
 ### Official Subagents (Haiku-based)
-Lightweight subagents for mechanical tasks. Invoked via `Task tool` with `subagent_type`.
+Lightweight subagents for mechanical tasks. Invoked via `Task tool` with `subagent_type: "general-purpose"` and `model: "haiku"`.
+
+**Invocation pattern:**
+```yaml
+Task tool:
+  subagent_type: "general-purpose"
+  model: "haiku"
+  prompt: |
+    Read and follow: .pennyfarthing/agents/{subagent-name}.md
+
+    {PARAMETERS}
+```
 
 - **`workflow-status-check.md`** - Detect workflow state
 - **`generic-sm-setup.md`** - Research OR setup mode (Story 31-11)
@@ -304,9 +315,12 @@ Subagents can run in background using Claude Code's `run_in_background` paramete
 
 ```yaml
 Task tool:
-  subagent_type: "testing-runner"
+  subagent_type: "general-purpose"
+  model: "haiku"
   run_in_background: true
   prompt: |
+    Read and follow: .pennyfarthing/agents/testing-runner.md
+
     REPOS: all
     CONTEXT: Background test run while implementing
     RUN_ID: bg-test-001

package/pennyfarthing-dist/agents/architect.md

@@ -17,10 +17,21 @@ Auto-loaded by `agent-session.sh start` from theme config. See output above.
 <helpers>
 From theme config. Model: haiku. Tasks: Architecture scanning, pattern analysis, codebase exploration.
 
-- **Official subagents:** (use `subagent_type: "{name}"`)
-  - `workflow-status-check` - Scan sprint state and active sessions
-  - `testing-runner` - Verify builds pass after design changes
-  - `sm-file-summary` - Summarize files for context gathering
+- **Subagents:** (use `subagent_type: "general-purpose"` with `model: "haiku"`)
+  - `workflow-status-check.md` - Scan sprint state and active sessions
+  - `testing-runner.md` - Verify builds pass after design changes
+  - `sm-file-summary.md` - Summarize files for context gathering
+
+- **Invocation pattern:**
+  ```yaml
+  Task tool:
+    subagent_type: "general-purpose"
+    model: "haiku"
+    prompt: |
+      Read and follow: .pennyfarthing/agents/{subagent-name}.md
+
+      {PARAMETERS}
+  ```
 </helpers>
 
 <responsibilities>
@@ -140,8 +151,11 @@ When design changes may affect build:
 
 ```yaml
 Task tool:
-  subagent_type: "testing-runner"
+  subagent_type: "general-purpose"
+  model: "haiku"
   prompt: |
+    Read and follow: .pennyfarthing/agents/testing-runner.md
+
     REPOS: all
     CONTEXT: Verifying build after design change
     RUN_ID: architect-verify

package/pennyfarthing-dist/agents/dev.md

@@ -17,9 +17,20 @@ Auto-loaded by `agent-session.sh start` from theme config. See output above.
 <helpers>
 From theme config. Model: haiku. Tasks: run tests, gather results, update session for handoff
 
-- **Official subagents:** (use `subagent_type: "{name}"`)
-  - `testing-runner` - Run tests, gather results
-  - `generic-handoff` - Workflow-driven session update for handoff
+- **Subagents:** (use `subagent_type: "general-purpose"` with `model: "haiku"`)
+  - `testing-runner.md` - Run tests, gather results
+  - `generic-handoff.md` - Workflow-driven session update for handoff
+
+- **Invocation pattern:**
+  ```yaml
+  Task tool:
+    subagent_type: "general-purpose"
+    model: "haiku"
+    prompt: |
+      Read and follow: .pennyfarthing/agents/{subagent-name}.md
+
+      {PARAMETERS}
+  ```
 </helpers>
 
 <responsibilities>
@@ -176,8 +187,11 @@ Then spawn with detected workflow (tdd, trivial, etc.):
 
 ```yaml
 Task tool:
-  subagent_type: "generic-handoff"
+  subagent_type: "general-purpose"
+  model: "haiku"
   prompt: |
+    Read and follow: .pennyfarthing/agents/generic-handoff.md
+
     STORY_ID: {value}
     WORKFLOW: {workflow from session}  # e.g., "tdd" or "trivial"
     CURRENT_PHASE: green               # or "implement" for trivial workflow

package/pennyfarthing-dist/agents/devops.md

@@ -17,10 +17,21 @@ Auto-loaded by `agent-session.sh start` from theme config. See output above.
 <helpers>
 From theme config. Model: haiku. Tasks: System checks, log analysis, config scanning.
 
-- **Official subagents:** (use `subagent_type: "{name}"`)
-  - `workflow-status-check` - Scan sprint state and active sessions
-  - `testing-runner` - Verify CI pipeline and tests pass
-  - `sm-file-summary` - Summarize configuration files
+- **Subagents:** (use `subagent_type: "general-purpose"` with `model: "haiku"`)
+  - `workflow-status-check.md` - Scan sprint state and active sessions
+  - `testing-runner.md` - Verify CI pipeline and tests pass
+  - `sm-file-summary.md` - Summarize configuration files
+
+- **Invocation pattern:**
+  ```yaml
+  Task tool:
+    subagent_type: "general-purpose"
+    model: "haiku"
+    prompt: |
+      Read and follow: .pennyfarthing/agents/{subagent-name}.md
+
+      {PARAMETERS}
+  ```
 </helpers>
 
 <responsibilities>
@@ -140,8 +151,11 @@ Before any deployment:
 
 ```yaml
 Task tool:
-  subagent_type: "testing-runner"
+  subagent_type: "general-purpose"
+  model: "haiku"
   prompt: |
+    Read and follow: .pennyfarthing/agents/testing-runner.md
+
     REPOS: all
     CONTEXT: Pre-deployment verification
     RUN_ID: devops-verify

package/pennyfarthing-dist/agents/generic-handoff.md

@@ -104,8 +104,11 @@ Based on the gate type from the workflow, run the appropriate checks.
    If no valid cache or TEST_RESULT not provided, delegate to testing-runner:
    ```yaml
    Task tool:
-     subagent_type: "testing-runner"
+     subagent_type: "general-purpose"
+     model: "haiku"
      prompt: |
+       Read and follow: .pennyfarthing/agents/testing-runner.md
+
        REPOS: {REPOS}
        CONTEXT: TEA handoff - verify tests are RED
        RUN_ID: {STORY_ID}-tea-handoff

package/pennyfarthing-dist/agents/orchestrator.md

@@ -17,12 +17,23 @@ Auto-loaded by `agent-session.sh start` from theme config. See output above.
 <helpers>
 From theme config. Model: haiku. Tasks: Status checks, metrics gathering, file scanning.
 
-- **Official subagents:** (use `subagent_type: "{name}"`)
-  - `workflow-status-check` - Scan session files and git status
-  - `testing-runner` - Run tests to verify changes
-  - `sm-file-summary` - Summarize agent files for audit
-  - `generic-handoff` - Update session for phase transitions
-  - `Explore` - Search for patterns across codebase
+- **Subagents:** (use `subagent_type: "general-purpose"` with `model: "haiku"`)
+  - `workflow-status-check.md` - Scan session files and git status
+  - `testing-runner.md` - Run tests to verify changes
+  - `sm-file-summary.md` - Summarize agent files for audit
+  - `generic-handoff.md` - Update session for phase transitions
+  - `Explore` - Search for patterns across codebase (Claude Code built-in)
+
+- **Invocation pattern:**
+  ```yaml
+  Task tool:
+    subagent_type: "general-purpose"
+    model: "haiku"
+    prompt: |
+      Read and follow: .pennyfarthing/agents/{subagent-name}.md
+
+      {PARAMETERS}
+  ```
 </helpers>
 
 <responsibilities>
@@ -238,8 +249,11 @@ REFLECT: I should follow this pattern for consistency
 Never run `just test`, `npm test`, etc. directly. Always spawn:
 ```yaml
 Task tool:
-  subagent_type: "testing-runner"
+  subagent_type: "general-purpose"
+  model: "haiku"
   prompt: |
+    Read and follow: .pennyfarthing/agents/testing-runner.md
+
     REPOS: pennyfarthing
     CONTEXT: Verify agent file changes don't break tests
     RUN_ID: orchestrator-verify
@@ -294,8 +308,11 @@ See `/dev-patterns` skill → "Turn-Efficient Patterns" for complete guidance.
 After completing file updates, spawn handoff helper:
 ```yaml
 Task tool:
-  subagent_type: "generic-handoff"
+  subagent_type: "general-purpose"
+  model: "haiku"
   prompt: |
+    Read and follow: .pennyfarthing/agents/generic-handoff.md
+
     STORY_ID: {value}
     WORKFLOW: agent-docs
     CURRENT_PHASE: implement

package/pennyfarthing-dist/agents/pm.md

@@ -17,9 +17,20 @@ Auto-loaded by `agent-session.sh start` from theme config. See output above.
 <helpers>
 From theme config. Model: haiku. Tasks: Backlog scanning, Jira queries, velocity calculation, status checks.
 
-- **Official subagents:** (use `subagent_type: "{name}"`)
-  - `workflow-status-check` - Scan sprint state and active sessions
-  - `sm-file-summary` - Summarize files for context gathering
+- **Subagents:** (use `subagent_type: "general-purpose"` with `model: "haiku"`)
+  - `workflow-status-check.md` - Scan sprint state and active sessions
+  - `sm-file-summary.md` - Summarize files for context gathering
+
+- **Invocation pattern:**
+  ```yaml
+  Task tool:
+    subagent_type: "general-purpose"
+    model: "haiku"
+    prompt: |
+      Read and follow: .pennyfarthing/agents/{subagent-name}.md
+
+      {PARAMETERS}
+  ```
 </helpers>
 
 <responsibilities>

package/pennyfarthing-dist/agents/reviewer-preflight.md

@@ -97,58 +97,16 @@ fi
 
 Spawn a testing-runner subagent with:
 ```yaml
-subagent_type: "testing-runner"
-model: "haiku"
-description: "run tests"
-prompt: |
-  You are a testing runner for the Conductor project.
-  Run tests and report structured results.
-
-  ## Skills Reference
-  Read the testing skill at .claude/skills/testing/SKILL.md for test commands.
-  For troubleshooting failures, see .claude/skills/testing/references/troubleshooting.md
-
-  ## Project Info
-  - Project root: $CLAUDE_PROJECT_DIR (set by SessionStart hook)
-  - Repo(s) to test: {REPO}
-  - Context: PR review pre-flight for Story {STORY_ID}
-  - Run ID: {STORY_ID}-review
-
-  ## Execute Tests and Lints
-
-  Use repo-utils.sh for dynamic repo handling:
-  ```bash
-  source $CLAUDE_PROJECT_DIR/scripts/repo-utils.sh
-  RUN_ID="{STORY_ID}-review"
-
-  for repo in $(get_repo_names); do
-      repo_path=$(get_repo_path "$repo")
-      test_cmd=$(get_test_command "$repo")
-      lint_cmd=$(get_lint_command "$repo")
-
-      cd $CLAUDE_PROJECT_DIR/$repo_path
-
-      # Run tests
-      if [[ -n "$test_cmd" ]]; then
-          $test_cmd 2>&1 | tee $CLAUDE_PROJECT_DIR/.session/test-{STORY_ID}-reviewer-verify.log
-      fi
-
-      # Run linter
-      if [[ -n "$lint_cmd" ]]; then
-          $lint_cmd 2>&1 | tee $CLAUDE_PROJECT_DIR/.session/lint-{STORY_ID}-${repo}.log
-      fi
-  done
-  ```
-
-  ## Check for Forbidden Skip Patterns
-  ```bash
-  source $CLAUDE_PROJECT_DIR/scripts/repo-utils.sh
-  for repo in $(get_repo_names); do
-      check_skip_violations "$repo"
-  done
-  ```
-
-  ## Output structured results per testing-runner.md format
+Task tool:
+  subagent_type: "general-purpose"
+  model: "haiku"
+  description: "run tests"
+  prompt: |
+    Read and follow: .pennyfarthing/agents/testing-runner.md
+
+    REPOS: {REPOS}
+    CONTEXT: PR review pre-flight for Story {STORY_ID}
+    RUN_ID: {STORY_ID}-review
 ```
 
 If you cannot spawn a subagent, run the tests directly using the testing skill commands.

package/pennyfarthing-dist/agents/reviewer.md

@@ -35,10 +35,21 @@ A bug you miss ships to production. A security hole you miss gets exploited. An
 <helpers>
 From theme config. Model: haiku. Tasks: gather pre-flight data, update session for approval/rejection
 
-- **Official subagents:** (use `subagent_type: "{name}"`)
-  - `testing-runner` - Run tests
-  - `reviewer-preflight` - Gather pre-flight data (tests, lint, smells)
-  - `generic-handoff` - Workflow-driven session update (approve or reject)
+- **Subagents:** (use `subagent_type: "general-purpose"` with `model: "haiku"`)
+  - `testing-runner.md` - Run tests
+  - `reviewer-preflight.md` - Gather pre-flight data (tests, lint, smells)
+  - `generic-handoff.md` - Workflow-driven session update (approve or reject)
+
+- **Invocation pattern:**
+  ```yaml
+  Task tool:
+    subagent_type: "general-purpose"
+    model: "haiku"
+    prompt: |
+      Read and follow: .pennyfarthing/agents/{subagent-name}.md
+
+      {PARAMETERS}
+  ```
 </helpers>
 
 <responsibilities>
@@ -109,8 +120,11 @@ Spawn Helper to gather mechanical data:
 
 ```yaml
 Task tool:
-  subagent_type: "reviewer-preflight"
+  subagent_type: "general-purpose"
+  model: "haiku"
   prompt: |
+    Read and follow: .pennyfarthing/agents/reviewer-preflight.md
+
     STORY_ID: {value}
     REPOS: {value}
     BRANCH: {value}
@@ -241,8 +255,11 @@ Then spawn with detected workflow:
 ```yaml
 # Approval
 Task tool:
-  subagent_type: "generic-handoff"
+  subagent_type: "general-purpose"
+  model: "haiku"
   prompt: |
+    Read and follow: .pennyfarthing/agents/generic-handoff.md
+
     STORY_ID: {value}
     WORKFLOW: {workflow from session}  # e.g., "tdd" or "trivial"
     CURRENT_PHASE: review
@@ -252,8 +269,11 @@ Task tool:
 
 # Rejection
 Task tool:
-  subagent_type: "generic-handoff"
+  subagent_type: "general-purpose"
+  model: "haiku"
   prompt: |
+    Read and follow: .pennyfarthing/agents/generic-handoff.md
+
     STORY_ID: {value}
     WORKFLOW: {workflow from session}  # e.g., "tdd" or "trivial"
     CURRENT_PHASE: review

package/pennyfarthing-dist/agents/sm.md

@@ -16,20 +16,25 @@ Auto-loaded by `agent-session.sh start` from theme config. See output above.
 <helpers>
 From theme config. Model: haiku. Tasks: Status checks, backlog scans, file summaries, Jira updates, session archival.
 
-- **Official subagents:** (use `subagent_type: "{name}"`)
-  - `workflow-status-check` - Scan session files and git status
-  - `testing-runner` - Run tests
-  - `generic-sm-setup` - Research backlog OR setup story (mode: research|setup)
-  - `generic-sm-finish` - Preflight checks OR execute finish (phase: preflight|execute)
-  - `generic-handoff` - Workflow-driven phase transitions (TEA/Dev/Reviewer)
-  - `sm-handoff` - SM→TEA/Dev handoff with Jira claim and branch verification
-  - `sm-file-summary` - Read and summarize files for context
-
-- **Removed subagents:** (deleted - use consolidated versions above)
-  - `sm-work-research` → use `generic-sm-setup` with MODE=research
-  - `sm-story-setup` → use `generic-sm-setup` with MODE=setup
-  - `sm-finish-bookkeeping` → use `generic-sm-finish` with PHASE=preflight
-  - `sm-finish-execution` → use `generic-sm-finish` with PHASE=execute
+- **Subagents:** (use `subagent_type: "general-purpose"` with `model: "haiku"`)
+  - `workflow-status-check.md` - Scan session files and git status
+  - `testing-runner.md` - Run tests
+  - `generic-sm-setup.md` - Research backlog OR setup story (mode: research|setup)
+  - `generic-sm-finish.md` - Preflight checks OR execute finish (phase: preflight|execute)
+  - `generic-handoff.md` - Workflow-driven phase transitions (TEA/Dev/Reviewer)
+  - `sm-handoff.md` - SM→TEA/Dev handoff with Jira claim and branch verification
+  - `sm-file-summary.md` - Read and summarize files for context
+
+- **Invocation pattern:**
+  ```yaml
+  Task tool:
+    subagent_type: "general-purpose"
+    model: "haiku"
+    prompt: |
+      Read and follow: .pennyfarthing/agents/{subagent-name}.md
+
+      {PARAMETERS}
+  ```
 </helpers>
 
 <responsibilities>
@@ -120,8 +125,11 @@ REFLECT: I should clarify AC4 with the user before proceeding.
 1. Run workflow status check:
    ```yaml
    Task tool:
-     subagent_type: "workflow-status-check"
+     subagent_type: "general-purpose"
+     model: "haiku"
      prompt: |
+       Read and follow: .pennyfarthing/agents/workflow-status-check.md
+
        CALLING_AGENT: SM
    ```
 2. Helper returns: `FINISH_STATE`, `NEW_WORK_STATE`, or `IN_PROGRESS_STATE`
@@ -136,8 +144,11 @@ I send helper to check the workflow status before anything else.
 
 ```yaml
 Task tool:
-  subagent_type: "workflow-status-check"
+  subagent_type: "general-purpose"
+  model: "haiku"
   prompt: |
+    Read and follow: .pennyfarthing/agents/workflow-status-check.md
+
     CALLING_AGENT: SM
 ```
 
@@ -169,8 +180,11 @@ Task tool:
 
 ```yaml
 Task tool:
-  subagent_type: "generic-sm-finish"
+  subagent_type: "general-purpose"
+  model: "haiku"
   prompt: |
+    Read and follow: .pennyfarthing/agents/generic-sm-finish.md
+
     PHASE: preflight
     STORY_ID: {value}
     JIRA_KEY: {value from session/YAML jira field, or omit if not found}
@@ -211,8 +225,11 @@ I read helper's bookkeeping report and write `sprint/context/story-{X-Y}-summary
 
 ```yaml
 Task tool:
-  subagent_type: "generic-sm-finish"
+  subagent_type: "general-purpose"
+  model: "haiku"
   prompt: |
+    Read and follow: .pennyfarthing/agents/generic-sm-finish.md
+
     PHASE: execute
     STORY_ID: {value}
     SUMMARY_CONTENT: {value}
@@ -234,8 +251,11 @@ Helper does:
 
 ```yaml
 Task tool:
-  subagent_type: "generic-sm-setup"
+  subagent_type: "general-purpose"
+  model: "haiku"
   prompt: |
+    Read and follow: .pennyfarthing/agents/generic-sm-setup.md
+
     MODE: research
 ```
 
@@ -261,8 +281,11 @@ I receive helper's research report and present to the user:
 
 ```yaml
 Task tool:
-  subagent_type: "sm-file-summary"
+  subagent_type: "general-purpose"
+  model: "haiku"
   prompt: |
+    Read and follow: .pennyfarthing/agents/sm-file-summary.md
+
     STORY_ID: {value}
     FILE_LIST: |
       path/to/file1.go
@@ -344,8 +367,11 @@ Then spawn setup with the detected workflow:
 
 ```yaml
 Task tool:
-  subagent_type: "generic-sm-setup"
+  subagent_type: "general-purpose"
+  model: "haiku"
   prompt: |
+    Read and follow: .pennyfarthing/agents/generic-sm-setup.md
+
     MODE: setup
     STORY_ID: {value}
     JIRA_KEY: {value}
@@ -373,8 +399,11 @@ After story setup, spawn Helper to update session file for handoff:
 
 ```yaml
 Task tool:
-  subagent_type: "sm-handoff"
+  subagent_type: "general-purpose"
+  model: "haiku"
   prompt: |
+    Read and follow: .pennyfarthing/agents/sm-handoff.md
+
     STORY_ID: {value}
     REPOS: {value}
     TITLE: {value}

package/pennyfarthing-dist/agents/tea.md

@@ -17,9 +17,20 @@ Auto-loaded by `agent-session.sh start` from theme config. See output above.
 <helpers>
 From theme config. Model: haiku. Tasks: run tests, gather results, update session for handoff
 
-- **Official subagents:** (use `subagent_type: "{name}"`)
-  - `testing-runner` - Run tests, gather results
-  - `generic-handoff` - Workflow-driven session update for handoff
+- **Subagents:** (use `subagent_type: "general-purpose"` with `model: "haiku"`)
+  - `testing-runner.md` - Run tests, gather results
+  - `generic-handoff.md` - Workflow-driven session update for handoff
+
+- **Invocation pattern:**
+  ```yaml
+  Task tool:
+    subagent_type: "general-purpose"
+    model: "haiku"
+    prompt: |
+      Read and follow: .pennyfarthing/agents/{subagent-name}.md
+
+      {PARAMETERS}
+  ```
 </helpers>
 
 <responsibilities>
@@ -151,8 +162,11 @@ Then spawn with detected workflow:
 
 ```yaml
 Task tool:
-  subagent_type: "generic-handoff"
+  subagent_type: "general-purpose"
+  model: "haiku"
   prompt: |
+    Read and follow: .pennyfarthing/agents/generic-handoff.md
+
     STORY_ID: {value}
     WORKFLOW: {workflow from session}  # e.g., "tdd"
     CURRENT_PHASE: red

package/pennyfarthing-dist/agents/testing-runner.md

@@ -65,9 +65,12 @@ The testing-runner can be spawned in background mode, allowing the main agent to
 
 ```yaml
 Task tool:
-  subagent_type: "testing-runner"
+  subagent_type: "general-purpose"
+  model: "haiku"
   run_in_background: true
   prompt: |
+    Read and follow: .pennyfarthing/agents/testing-runner.md
+
     REPOS: all
     CONTEXT: Background test run while implementing
     RUN_ID: bg-test-001

package/pennyfarthing-dist/skills/cyclist/SKILL.md

@@ -20,6 +20,21 @@ Cyclist is a visual terminal interface for Claude Code that displays:
 - Story/session progress tracking
 - Git status and context information
 
+## Quick Start (Recommended)
+
+Use `just` commands from the project root:
+
+```bash
+# Start Cyclist Electron (recommended)
+just cyclist-electron
+
+# Start Cyclist web server only (browser-based)
+just cyclist-web
+
+# Start Cyclist for a different project
+just cyclist-electron project_dir=/path/to/project
+```
+
 ## Environment Variables
 
 | Variable | Description | Default |
@@ -38,6 +53,20 @@ Cyclist is a visual terminal interface for Claude Code that displays:
 
 ## Launch Commands
 
+### Using Just (Recommended)
+
+```bash
+# Electron mode (from any pennyfarthing project)
+just cyclist-electron
+
+# Web mode (browser-based)
+just cyclist-web
+
+# With explicit project directory
+just cyclist-electron project_dir=/path/to/project
+just cyclist-web project_dir=/path/to/project
+```
+
 ### Web Backend (Browser Mode)
 
 Run from the **cyclist package directory**:
@@ -62,19 +91,10 @@ cyclist /path/to/project
 
 # Direct launch via open
 open -a Cyclist --args --project-dir=/path/to/project
-```
-
-### Quick Launch Examples
-
-```bash
-# Web mode for current directory
-cd packages/cyclist && CYCLIST_PROJECT_DIR=$PWD npm start
-
-# Web mode on custom port
-cd packages/cyclist && PORT=3000 CYCLIST_PROJECT_DIR=/path npm start
 
-# Dev mode with hot reload
-cd packages/cyclist && CYCLIST_DEV_WEB=1 CYCLIST_PROJECT_DIR=/path npm run dev:server
+# Development (from packages/cyclist)
+cd packages/cyclist
+CYCLIST_PROJECT_DIR=/path/to/project npm run dev
 ```
 
 ## Port Auto-Discovery
@@ -91,27 +111,61 @@ From `packages/cyclist/`:
 |--------|-------------|
 | `npm start` | Run production server |
 | `npm run dev` | Electron dev mode with file watching |
+| `npm run dev:once` | Build and run Electron once (no watching) |
 | `npm run dev:web` | Web server with tsx watch |
 | `npm run dev:server` | Server-only with tsx watch |
 | `npm run build` | Compile TypeScript |
 
+## Just Commands Reference
+
+| Command | Description |
+|---------|-------------|
+| `just cyclist-electron` | Start Electron dev mode |
+| `just cyclist-web` | Start web server mode |
+| `just cyclist-build` | Build Cyclist TypeScript |
+| `just cyclist-rebuild` | Rebuild native modules (node-pty) |
+| `just cyclist-setup` | Full clean + install + rebuild + build |
+| `just cyclist-build-and-install` | Build and install Cyclist.app |
+| `just test-cyclist` | Run Cyclist tests |
+
 ## Requirements
 
-- Project must have `.claude/` directory (Pennyfarthing-enabled)
-- For Electron: Cyclist.app must be installed
+- Project must have `.pennyfarthing/` directory with config (Pennyfarthing-enabled)
+- For Electron: Cyclist.app must be installed, or run from source
 - For web: Run from `packages/cyclist/` directory
 
 ## Troubleshooting
 
+### Window not appearing (Electron)
+
+The `package.json` has `"main": "dist/server.js"` for npm module use. The `dev` scripts explicitly run `electron dist/main.js` to use the correct entry point. If you run `electron .` directly, it will run the web server instead of the Electron main process.
+
+**Fix:** Use `just cyclist-electron` or `npm run dev` which run `electron dist/main.js`.
+
 ### Server won't start
-- Ensure you're in the cyclist package directory
+
+- Ensure you're in the cyclist package directory (or use `just` commands)
 - Run `npm run build` first if dist/ is stale
 - Check console for port conflict messages
 
 ### No portraits showing
+
 - Verify `pennyfarthing-dist/personas/portraits/` exists
-- Check theme in `.claude/persona-config.yaml`
+- Check theme in `.pennyfarthing/config.local.yaml`
 
 ### "Not a Pennyfarthing project"
-- Ensure project has `.claude/` directory
+
+- Ensure project has `.pennyfarthing/` directory with `config.local.yaml` or agent symlinks
+- Or has `.claude/` directory with persona-config.yaml (legacy)
 - Run `pennyfarthing init` in the project first
+- Or set `CYCLIST_PROJECT_DIR` to point to a valid project
+
+### Native module issues (node-pty)
+
+```bash
+# Rebuild native modules for current Electron version
+just cyclist-rebuild
+
+# Or full setup from scratch
+just cyclist-setup
+```