@pennyfarthing/core 6.6.0

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

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

@@ -0,0 +1,222 @@
+---
+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

@@ -0,0 +1,172 @@
+---
+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)