@pennyfarthing/core 10.0.0 → 10.0.2

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

@@ -0,0 +1,414 @@
+---
+name: just
+description: |
+  Run just recipes for project tasks. This skill should be used when starting dev servers,
+  running tests, managing Cyclist, generating portraits, or writing new justfile recipes.
+args: "[recipe] [args...]"
+---
+
+# /just - Project Task Runner
+
+<run>
+Main commands:
+- `just --list` - List all available recipes
+- `just <recipe>` - Run a specific recipe (e.g., `just build`, `just test`, `just cyclist`)
+</run>
+
+<output>
+- `just --list` outputs a list of available recipes with their descriptions
+- Individual recipe commands output their execution results (build logs, test results, etc.) depending on the recipe
+</output>
+
+`just` is a command runner for project tasks. All commands run from the **project root**.
+
+## Commands
+
+### `/just` or `/just --list`
+
+List all available recipes.
+
+**Run:**
+```bash
+just --list
+```
+
+**Output:** Recipe names with descriptions.
+
+---
+
+### `/just build`
+
+Build all packages in the monorepo.
+
+**Run:**
+```bash
+just build
+```
+
+**What it does:** Runs `pnpm run build` to compile TypeScript across all packages.
+
+---
+
+### `/just test`
+
+Run tests for all packages.
+
+**Run:**
+```bash
+just test
+```
+
+**What it does:** Runs `pnpm test` which executes Node.js native test runner across the monorepo.
+
+---
+
+### `/just test-cyclist`
+
+Run tests for the Cyclist package only.
+
+**Run:**
+```bash
+just test-cyclist
+```
+
+**What it does:** Runs `npm test` in `packages/cyclist/`.
+
+---
+
+### `/just test-cyclist-watch`
+
+Run Cyclist tests in watch mode for TDD workflow.
+
+**Run:**
+```bash
+just test-cyclist-watch
+```
+
+**What it does:** Runs Vitest in watch mode, re-running tests on file changes.
+
+---
+
+### `/just install`
+
+Install dependencies for all packages.
+
+**Run:**
+```bash
+just install
+```
+
+**What it does:** Runs `pnpm install` to install dependencies across the monorepo.
+
+---
+
+## Cyclist Commands
+
+The `cyclist` recipe is the main entry point for Cyclist operations.
+
+### `/just cyclist` (default)
+
+Launch Cyclist in Electron mode with folder picker.
+
+**Run:**
+```bash
+just cyclist
+```
+
+**What it does:** Starts Cyclist Electron app, prompting to select a project directory.
+
+---
+
+### `/just cyclist here`
+
+Launch Cyclist for the current directory.
+
+**Run:**
+```bash
+just cyclist here
+```
+
+**What it does:** Starts Cyclist Electron app with `pwd` as the project directory.
+
+---
+
+### `/just cyclist web`
+
+Launch Cyclist in web dev mode with hot reload.
+
+**Run:**
+```bash
+just cyclist web
+```
+
+**What it does:** Starts the web server with Vite for browser-based development.
+
+---
+
+### `/just cyclist server`
+
+Start Cyclist web server only (no browser).
+
+**Run:**
+```bash
+just cyclist server
+```
+
+**What it does:** Starts the backend server for headless or remote access.
+
+---
+
+### `/just cyclist verbose`
+
+Enable debug logging for troubleshooting.
+
+**Run:**
+```bash
+just cyclist verbose
+```
+
+**Combine flags:**
+```bash
+just cyclist here verbose
+just cyclist web verbose
+```
+
+---
+
+### `/just cyclist dir=<path>`
+
+Launch Cyclist for a specific project directory.
+
+**Run:**
+```bash
+just cyclist dir=/path/to/project
+```
+
+**Arguments:**
+| Arg | Required | Description |
+|-----|----------|-------------|
+| `dir=` | Yes | Absolute path to project directory |
+
+---
+
+### `/just cyclist setup`
+
+First-time setup for Cyclist development.
+
+**Run:**
+```bash
+just cyclist setup
+```
+
+**What it does:**
+1. Cleans stale artifacts (`rm -rf packages/cyclist/dist/`)
+2. Installs dependencies (`pnpm install`)
+3. Rebuilds native modules (`npx electron-rebuild`)
+4. Builds TypeScript (`pnpm run build`)
+
+---
+
+### `/just cyclist doctor`
+
+Diagnose Cyclist setup issues.
+
+**Run:**
+```bash
+just cyclist doctor
+just cyclist doctor --fix
+```
+
+**Arguments:**
+| Arg | Required | Description |
+|-----|----------|-------------|
+| `--fix` | No | Auto-repair detected issues |
+
+**What it does:** Checks for common setup problems and optionally fixes them.
+
+---
+
+### `/just cyclist build`
+
+Build Cyclist TypeScript only.
+
+**Run:**
+```bash
+just cyclist build
+```
+
+**What it does:** Compiles TypeScript in `packages/cyclist/`. Builds workspace dependencies first if missing.
+
+---
+
+### `/just cyclist clean`
+
+Remove Cyclist build artifacts.
+
+**Run:**
+```bash
+just cyclist clean
+```
+
+**What it does:** Removes `packages/cyclist/dist/` directory.
+
+---
+
+### `/just cyclist rebuild`
+
+Rebuild native modules (node-pty) for Electron.
+
+**Run:**
+```bash
+just cyclist rebuild
+```
+
+**What it does:** Runs `npx electron-rebuild` in `packages/cyclist/`.
+
+**When needed:** After Node.js version changes or native module errors.
+
+---
+
+### `/just cyclist package`
+
+Build Cyclist Electron app for distribution.
+
+**Run:**
+```bash
+just cyclist package
+```
+
+**What it does:** Runs `npm run build:electron` to create distributable app.
+
+---
+
+### `/just cyclist install`
+
+Install Cyclist app and CLI.
+
+**Run:**
+```bash
+just cyclist install
+```
+
+**What it does:**
+1. Installs `Cyclist.app` to `/Applications`
+2. Installs `cyclist` CLI to `/usr/local/bin`
+
+---
+
+## Portrait Commands
+
+Generate AI portraits for persona themes.
+
+### `/just portraits <theme>`
+
+Generate portraits for a specific theme.
+
+**Run:**
+```bash
+just portraits arthurian-mythos
+```
+
+**Arguments:**
+| Arg | Required | Description |
+|-----|----------|-------------|
+| `theme` | Yes | Theme name (e.g., `arthurian-mythos`, `the-expanse`) |
+
+---
+
+### `/just portraits-all`
+
+Generate portraits for all themes.
+
+**Run:**
+```bash
+just portraits-all
+```
+
+**Warning:** This is time-intensive. Generates portraits for all 102 themes.
+
+---
+
+### `/just portraits-preview <theme>`
+
+Preview portraits for a theme without saving.
+
+**Run:**
+```bash
+just portraits-preview arthurian-mythos
+```
+
+**Arguments:**
+| Arg | Required | Description |
+|-----|----------|-------------|
+| `theme` | Yes | Theme name to preview |
+
+---
+
+## Passing Arguments to Recipes
+
+Just recipes accept arguments directly (no `--` separator needed):
+
+```bash
+# Correct
+just test-cyclist --filter "B-001"
+just cyclist here verbose
+
+# WRONG - don't use --
+just test-cyclist -- --filter "B-001"
+```
+
+---
+
+## Inspecting Recipes
+
+### Show recipe definition
+
+**Run:**
+```bash
+just --show <recipe>
+```
+
+**Example:**
+```bash
+just --show cyclist
+# Shows the full recipe implementation
+```
+
+---
+
+## Quick Reference
+
+| Command | Description |
+|---------|-------------|
+| `just` | List available recipes |
+| `just build` | Build all packages |
+| `just test` | Run all tests |
+| `just test-cyclist` | Run Cyclist tests |
+| `just test-cyclist-watch` | Cyclist tests in watch mode |
+| `just install` | Install dependencies |
+| `just cyclist` | Electron + folder picker |
+| `just cyclist here` | Electron + current directory |
+| `just cyclist web` | Web dev mode |
+| `just cyclist server` | Web server only |
+| `just cyclist setup` | First-time setup |
+| `just cyclist doctor` | Diagnose issues |
+| `just cyclist build` | Build TypeScript |
+| `just cyclist clean` | Remove dist/ |
+| `just cyclist rebuild` | Rebuild native modules |
+| `just cyclist package` | Build Electron app |
+| `just cyclist install` | Install app + CLI |
+| `just portraits <theme>` | Generate theme portraits |
+| `just portraits-all` | Generate all portraits |
+| `just portraits-preview <theme>` | Preview portraits |
+
+## Dependencies
+
+```bash
+brew install just
+# or
+cargo install just
+```
+
+## Reference
+
+- **Official Docs:** https://just.systems/man/en/

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

@@ -0,0 +1,256 @@
+---
+name: mermaid
+description: Generate diagrams using Mermaid syntax. Use this skill when creating architecture diagrams, sequence diagrams, ER diagrams, flowcharts, or any visual documentation in markdown files.
+---
+
+<run>
+Generate Mermaid diagrams by writing code blocks with the `mermaid` language identifier in markdown files. Mermaid syntax is rendered natively by GitHub, GitLab, and most markdown editors. Choose the appropriate diagram type (flowchart, sequence, ER, class, or state) based on what you need to visualize.
+</run>
+
+<output>
+Mermaid code blocks that render as diagrams. Example output format:
+
+```mermaid
+flowchart TD
+    A[Start] --> B[Process]
+    B --> C[End]
+```
+
+The diagram renders visually in GitHub, GitLab, and compatible markdown viewers.
+</output>
+
+# Mermaid Diagram Skill
+
+## When to Use This Skill
+
+- Documenting system architecture or component relationships
+- Visualizing API request/response flows
+- Creating database schema diagrams from models
+- Illustrating state machines or workflows
+- Adding visual documentation to markdown files
+
+## Overview
+
+Mermaid is a JavaScript-based diagramming tool that renders markdown-like syntax into diagrams. GitHub, GitLab, and many markdown editors render Mermaid blocks natively.
+
+**No installation required** for GitHub rendering - just use fenced code blocks with `mermaid` language identifier.
+
+## Prerequisites
+
+### Option 1: GitHub/GitLab (Recommended)
+No setup needed. Wrap diagrams in triple backticks with `mermaid` language:
+
+~~~markdown
+```mermaid
+flowchart LR
+    A --> B
+```
+~~~
+
+### Option 2: Mermaid CLI (Local Rendering)
+```bash
+npm install -g @mermaid-js/mermaid-cli
+mmdc -i input.mmd -o output.svg
+```
+
+### Option 3: VS Code Extension
+Install "Markdown Preview Mermaid Support" extension for live preview.
+
+## Flowchart Diagrams
+
+Use for architecture, decision trees, and process flows.
+
+### Basic Syntax
+```mermaid
+flowchart TD
+    A[Rectangle] --> B(Rounded)
+    B --> C{Diamond}
+    C -->|Yes| D[Result 1]
+    C -->|No| E[Result 2]
+```
+
+### Direction Options
+- `TD` or `TB` - Top to bottom
+- `LR` - Left to right
+- `BT` - Bottom to top
+- `RL` - Right to left
+
+### Architecture Example
+```mermaid
+flowchart TD
+    subgraph Client
+        UI[React App]
+    end
+    subgraph Server
+        API[Express API]
+        Auth[Auth Service]
+    end
+    subgraph Data
+        DB[(PostgreSQL)]
+        Cache[(Redis)]
+    end
+
+    UI -->|HTTP| API
+    API --> Auth
+    API --> DB
+    API --> Cache
+```
+
+## Sequence Diagrams
+
+Use for API flows, authentication sequences, and message passing.
+
+### Basic Syntax
+```mermaid
+sequenceDiagram
+    participant C as Client
+    participant S as Server
+    participant DB as Database
+
+    C->>S: POST /api/users
+    S->>DB: INSERT user
+    DB-->>S: OK
+    S-->>C: 201 Created
+```
+
+### Arrow Types
+- `->>` Solid line with arrowhead
+- `-->>` Dotted line with arrowhead
+- `-x` Solid line with X (async)
+- `--x` Dotted line with X
+
+### With Loops and Conditionals
+```mermaid
+sequenceDiagram
+    participant U as User
+    participant A as API
+    participant Auth as Auth Service
+
+    U->>A: Login request
+    A->>Auth: Validate credentials
+
+    alt Valid credentials
+        Auth-->>A: Token
+        A-->>U: 200 OK + Token
+    else Invalid
+        Auth-->>A: Error
+        A-->>U: 401 Unauthorized
+    end
+
+    loop Every 15 minutes
+        U->>A: Refresh token
+        A-->>U: New token
+    end
+```
+
+## ER Diagrams
+
+Use for database schemas and entity relationships.
+
+### Basic Syntax
+```mermaid
+erDiagram
+    USER ||--o{ ORDER : places
+    ORDER ||--|{ LINE_ITEM : contains
+    PRODUCT ||--o{ LINE_ITEM : "ordered in"
+```
+
+### Cardinality Notation
+- `||` - Exactly one
+- `o|` - Zero or one
+- `}|` - One or more
+- `}o` - Zero or more
+
+### With Attributes
+```mermaid
+erDiagram
+    USER {
+        int id PK
+        string email UK
+        string name
+        timestamp created_at
+    }
+    ORDER {
+        int id PK
+        int user_id FK
+        decimal total
+        string status
+    }
+    USER ||--o{ ORDER : places
+```
+
+## Class Diagrams
+
+Use for object models and component relationships.
+
+### Basic Syntax
+```mermaid
+classDiagram
+    class User {
+        +int id
+        +string email
+        +login()
+        +logout()
+    }
+    class Order {
+        +int id
+        +decimal total
+        +submit()
+    }
+    User "1" --> "*" Order : places
+```
+
+### Relationship Types
+- `<|--` Inheritance
+- `*--` Composition
+- `o--` Aggregation
+- `-->` Association
+- `..>` Dependency
+
+## State Diagrams
+
+Use for state machines and workflow states.
+
+### Basic Syntax
+```mermaid
+stateDiagram-v2
+    [*] --> Draft
+    Draft --> Review : submit
+    Review --> Approved : approve
+    Review --> Draft : reject
+    Approved --> Published : publish
+    Published --> [*]
+```
+
+### With Nested States
+```mermaid
+stateDiagram-v2
+    [*] --> Active
+
+    state Active {
+        [*] --> Idle
+        Idle --> Processing : start
+        Processing --> Idle : complete
+    }
+
+    Active --> Suspended : suspend
+    Suspended --> Active : resume
+    Active --> [*] : terminate
+```
+
+## Best Practices
+
+1. **Keep diagrams focused** - One concept per diagram, split complex systems into multiple diagrams
+2. **Use meaningful labels** - `API` not `A`, `Database` not `DB` (unless space-constrained)
+3. **Add subgraphs** for grouping related components in flowcharts
+4. **Use aliases** in sequence diagrams (`participant C as Client`) for readability
+5. **Include cardinality** in ER diagrams - relationships are ambiguous without it
+6. **Test rendering** on GitHub before committing - some syntax varies between versions
+7. **Link to details** - Diagrams show structure; link to docs for implementation details
+
+## Reference Documentation
+
+- **Official Docs:** https://mermaid.js.org/
+- **Live Editor:** https://mermaid.live/
+- **GitHub Support:** https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/creating-diagrams
+- **Syntax Reference:** https://mermaid.js.org/syntax/flowchart.html