@pennyfarthing/core 7.0.2 → 7.4.0

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

@@ -1,240 +0,0 @@
----
-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.
----
-
-# 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

package/pennyfarthing-dist/skills/otel/skill.md

@@ -1,222 +0,0 @@
----
-name: otel
-description: Claude Code OTEL telemetry format documentation. Use when working with OTEL span interception, enrichment, or correlation in Cyclist.
----
-
-# OTEL Skill - Claude Code Telemetry
-
-## Purpose
-
-Document the actual OTEL data Claude Code emits. This is ground truth, not speculation.
-
-**WARNING:** Do NOT assume fields exist. Check this document first.
-
-## Quick Start - Enable Debug Logging
-
-```bash
-# Option 1: Via just command
-just cyclist-electron true
-
-# Option 2: Via environment variable
-OTEL_DEBUG=true npm run dev
-
-# Option 3: Runtime toggle (in code or devtools)
-import { setOtelDebug } from './otlp-receiver.js';
-setOtelDebug(true);
-```
-
-Captures go to:
-- Console: `[OTEL-CAPTURE]` prefix
-- File: `/tmp/otel-capture.jsonl`
-
-View captures:
-```bash
-cat /tmp/otel-capture.jsonl | jq .
-# Or tail live:
-tail -f /tmp/otel-capture.jsonl | jq .
-```
-
-## Status
-
-**WORKING** - Stories 36-9, 36-10, 36-2, and 36-3 have established working enrichment patterns.
-
-## Known Facts (Verified)
-
-### LogRecord Structure
-
-Claude Code exports OTEL logs (not traces/spans). The logRecord structure:
-
-```typescript
-interface LogRecord {
-  timeUnixNano: string;       // Nanoseconds since epoch
-  observedTimeUnixNano: string;
-  body: { stringValue: string };  // Event name (e.g., "claude_code.tool_result")
-  attributes: Attribute[];    // Key-value pairs
-  droppedAttributesCount: number;
-  // NOTE: traceId and spanId are NOT present at logRecord level
-}
-```
-
-### What We Know Is MISSING
-
-- `traceId` - NOT in logRecord (Story 36-9 confirmed)
-- `spanId` - NOT in logRecord (Story 36-9 confirmed)
-- `tool_use_id` - NOT in OTEL attributes; use Claude message stream `block.id` instead
-
-### Event Types Observed
-
-| Event Name | Description |
-|------------|-------------|
-| `claude_code.tool_result` | Tool execution completed |
-| `claude_code.user_prompt` | User prompt submitted |
-| `claude_code.api_request` | API request made |
-
-### Tool Result Attributes (VERIFIED)
-
-```
-tool_name: string           // e.g., "Read", "Edit", "Bash"
-tool_parameters: string     // JSON string with tool-specific input
-tool_output: string         // Tool output (truncated to ~2000 chars)
-duration_ms: string|number  // Execution time in milliseconds
-success: string             // "true" or "false" as string
-error?: string              // Error message if failed
-```
-
-### tool_parameters Format by Tool (VERIFIED)
-
-**Read:**
-```json
-{ "file_path": "/absolute/path/to/file.ts" }
-```
-
-**Edit:**
-```json
-{
-  "file_path": "/absolute/path/to/file.ts",
-  "old_string": "text to replace",
-  "new_string": "replacement text"
-}
-```
-
-**Bash:**
-```json
-{
-  "command": "git status",
-  "description": "Check git status",
-  "timeout": 120000,
-  "run_in_background": false
-}
-```
-
-## Correlation Strategy (WORKING)
-
-Story 36-10 solved the correlation problem:
-
-1. Claude message stream provides `tool_use` with `block.id`, `block.name`, `block.input`
-2. Store in pending queue via `storePendingToolInput(toolId, toolName, input)`
-3. When OTEL arrives, match via `consumePendingToolInput(toolName, parsedToolParams)`
-4. **Key fix:** For Read/Edit, match on `file_path` first for precise correlation
-5. Fall back to FIFO by toolName for tools without file_path (e.g., Bash)
-6. Use `block.id` (toolId) as synthetic spanId for correlation map
-
-**Why this works:**
-- Claude message stream arrives BEFORE OTEL tool_result
-- file_path matching handles concurrent Read/Edit operations correctly
-- FIFO fallback works for Bash since commands are typically sequential
-
-## Enrichment Pipeline
-
-```
-Claude Message Stream           OTEL Logs
-       |                             |
-  tool_use event               tool_result event
-       |                             |
-storePendingToolInput()        consumePendingToolInput()
-       |                             |
-       +-----> Correlation <---------+
-                    |
-             enrichXxxSpan()
-                    |
-            ToolEvent with metadata
-                    |
-              Broadcast to UI
-```
-
-### Implemented Enrichments
-
-| Tool | Enrichment Function | Data Added |
-|------|---------------------|------------|
-| Read | `enrichReadSpan()` | fileSize, lineCount, language, gitStatus |
-| Edit | `enrichEditSpan()` | fileSize, language, gitStatus, diff (added/removed) |
-| Bash | `enrichBashSpan()` | command (redacted), exitCode, outputSummary, workingDirectory |
-
-### Secret Redaction (Bash)
-
-Commands are redacted before storage:
-- `password=xxx` → `password=[REDACTED]`
-- `token=xxx` → `token=[REDACTED]`
-- AWS credentials → `AWS_SECRET_ACCESS_KEY=[REDACTED]`
-- GitHub tokens (ghp_xxx) → `[REDACTED]`
-- Long base64 strings (40+ chars) → `[REDACTED]`
-
-## Files to Reference
-
-| File | Purpose |
-|------|---------|
-| `packages/cyclist/src/otlp-receiver.ts` | OTEL parsing, enrichment integration |
-| `packages/cyclist/src/span-correlation.ts` | Pending tool input queue, correlation map |
-| `packages/cyclist/src/file-enrichment.ts` | Enrichment functions (Read, Edit, Bash) |
-| `packages/cyclist/src/main.ts:820-824` | Message stream tool_use capture |
-
-## API
-
-```typescript
-// Enable/disable debug at runtime
-import { setOtelDebug, isOtelDebugEnabled } from './otlp-receiver.js';
-
-setOtelDebug(true);   // Start capturing
-setOtelDebug(false);  // Stop capturing
-isOtelDebugEnabled(); // Check status
-
-// Enrichment functions
-import { enrichReadSpan, enrichEditSpan, enrichBashSpan } from './file-enrichment.js';
-
-// Correlation
-import { storePendingToolInput, consumePendingToolInput } from './span-correlation.js';
-```
-
-## Captured Data Format
-
-Each line in `/tmp/otel-capture.jsonl` contains:
-
-```json
-{
-  "timestamp": "2026-01-15T08:00:00.000Z",
-  "eventName": "claude_code.tool_result",
-  "logRecordKeys": ["timeUnixNano", "body", "attributes", ...],
-  "traceId": null,
-  "spanId": null,
-  "attributes": [
-    { "key": "tool_name", "value": { "stringValue": "Read" } },
-    ...
-  ]
-}
-```
-
-## Related Stories
-
-| Story | Title | Status |
-|-------|-------|--------|
-| 36-1 | OTEL span interception and correlation | DONE |
-| 36-2 | Read/Edit tool enrichment | DONE |
-| 36-3 | Bash tool enrichment | DONE |
-| 36-4 | Search tool enrichment (Grep/Glob) | Backlog |
-| 36-5 | Task/subagent enrichment | Backlog |
-| 36-9 | Bug: missing trace/span IDs | DONE |
-| 36-10 | Bug: race condition in correlation | DONE |
-
-## Next Steps (Remaining Work)
-
-1. **36-4:** Add Grep/Glob enrichment (pattern, match count, file list)
-2. **36-5:** Add Task enrichment (subagent type, prompt summary, turn count)
-3. **36-6:** Export enriched spans to UI visualization

package/pennyfarthing-dist/skills/permissions/skill.md

@@ -1,172 +0,0 @@
----
-name: permissions
-description: Manage runtime permission grants - list active grants, add/revoke tool access, show grant details. Use for all permission-related operations.
----
-
-# Permission Management Skill
-
-## Overview
-
-Pennyfarthing uses a runtime permission system for tool access control. This skill provides commands to view and manage permission grants.
-
-## Quick Reference
-
-| Action | Command |
-|--------|---------|
-| List all grants | `/permissions` |
-| Grant tool access | `/permissions grant <tool> "<scope>"` |
-| Revoke tool access | `/permissions revoke <tool>` |
-| Show grant details | `/permissions show <tool>` |
-
-## Grant Types
-
-Permissions support three duration types:
-
-| Type | Duration | Storage |
-|------|----------|---------|
-| `once` | Single use | Memory only |
-| `session` | Until session ends | Memory only |
-| `always` | Persists forever | `.claude/settings.local.json` |
-
-## List Active Grants
-
-To see all currently active permission grants:
-
-```bash
-# Read grants from settings
-cat .claude/settings.local.json 2>/dev/null | jq '.permissions.grants // []'
-```
-
-Output shows:
-- Tool name
-- Scope pattern
-- Grant type
-- When granted
-- Uses remaining (for `once` type)
-
-If no grants exist, displays "No active permission grants."
-
-## Grant Tool Access
-
-Add a permission grant for a specific tool and scope:
-
-```
-/permissions grant <tool> "<scope>" [--type <once|session|always>]
-```
-
-**Parameters:**
-- `<tool>` - Tool name (e.g., `WebFetch`, `Bash`, `Read`)
-- `"<scope>"` - Scope pattern in quotes (e.g., `"*.github.com"`, `"git *"`)
-- `--type` - Grant duration (default: `session`)
-
-**Examples:**
-
-```bash
-# Grant WebFetch access to GitHub
-/permissions grant WebFetch "*.github.com"
-
-# Grant Bash read-only git commands (session-only)
-/permissions grant Bash "git status|git log|git diff"
-
-# Grant Read access to src directory (always)
-/permissions grant Read "src/**/*" --type always
-```
-
-**What happens:**
-1. Validates the tool name and scope
-2. Creates a `PermissionGrant` object with timestamp
-3. Stores in `.claude/settings.local.json` under `permissions.grants`
-4. Reports success with grant details
-
-## Revoke Tool Access
-
-Remove all grants for a specific tool:
-
-```
-/permissions revoke <tool>
-```
-
-**Examples:**
-
-```bash
-# Revoke all WebFetch grants
-/permissions revoke WebFetch
-
-# Revoke all Bash grants
-/permissions revoke Bash
-```
-
-**What happens:**
-1. Reads current grants from settings
-2. Filters out grants matching the tool name
-3. Writes updated grants back to settings
-4. Reports how many grants were removed
-
-## Show Grant Details
-
-Display detailed information about grants for a specific tool:
-
-```
-/permissions show <tool>
-```
-
-**Output includes:**
-- All grants for the specified tool
-- Scope patterns
-- Grant types
-- Timestamps
-- Remaining uses (for `once` type)
-
-## Storage Format
-
-Grants are stored in `.claude/settings.local.json`:
-
-```json
-{
-  "permissions": {
-    "grants": [
-      {
-        "tool": "WebFetch",
-        "scope": "*.github.com",
-        "grant_type": "session",
-        "granted_at": "2026-01-13T15:00:00.000Z"
-      },
-      {
-        "tool": "Bash",
-        "scope": "git *",
-        "grant_type": "always",
-        "granted_at": "2026-01-13T14:30:00.000Z"
-      }
-    ]
-  }
-}
-```
-
-## Permission Schema
-
-From `@pennyfarthing/core`:
-
-```typescript
-interface PermissionGrant {
-  tool: string;           // Tool name
-  scope: string;          // Scope pattern
-  grant_type: GrantType;  // 'once' | 'session' | 'always'
-  granted_at: string;     // ISO timestamp
-  uses_remaining?: number; // For 'once' type
-}
-```
-
-## Error Handling
-
-| Error | Cause | Solution |
-|-------|-------|----------|
-| "Invalid tool name" | Tool doesn't exist | Check available tools |
-| "Invalid scope pattern" | Empty or malformed scope | Provide quoted scope string |
-| "Settings file not found" | First-time use | File will be created |
-| "No grants found for tool" | Tool has no active grants | Nothing to revoke |
-
-## Related
-
-- **Story 33-1:** Permission Request Protocol (schema definitions)
-- **Story 33-3:** Cyclist Permission UI (visual management)
-- **Story 33-4:** Spot Permission Grants (inline approval)